From 3165ff6257257ac1101b7a766cc96922a00803db Mon Sep 17 00:00:00 2001 From: Emiya Kiritsugu Date: Tue, 31 Mar 2026 17:04:34 -0300 Subject: [PATCH 1/4] docs: create core antigravity configuration --- .antigravityignore | 9 +++++++++ AGENTS.md | 34 ++++++++++++++++++++++++++++++++++ 2 files changed, 43 insertions(+) create mode 100644 .antigravityignore create mode 100644 AGENTS.md diff --git a/.antigravityignore b/.antigravityignore new file mode 100644 index 00000000..c2d1c786 --- /dev/null +++ b/.antigravityignore @@ -0,0 +1,9 @@ +# .antigravityignore +# Exclude build output, massive dependencies, and binaries from the AI Context Engine +node_modules/ +.next/ +dist/ +public/media/ +.env* +coverage/ +*.lock diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..2b2a25cc --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,34 @@ +# AGENTS.md + +**Project:** Aegis Fitness OS (formerly Five Star Academy) +**Framework:** Next.js 15 (App Router), React 19, Tailwind CSS v4 +**Backend:** Server Actions, Prisma ORM, PostgreSQL (via Supabase) +**Build/Execution:** `pnpm` MUST be used. Do not use `npm` or `yarn`. + +## 1. Prime Directives +- **Atomic Operations:** Ensure commits are atomic and follow the semantic prefix convention (e.g. `feat:`, `fix:`, `docs:`, `ui:`). +- **Stateless Intelligence:** You MUST rely on `.ralph/PRD.md` for current project context before planning, and update `progress.txt` or `friction.log` appropriately. +- **Wait for Plan Approval:** Do NOT hallucinate architectures. When making major architectural changes or starting a new phase in the PRD, propose a plan using the system and wait for Principal human approval. + +## 2. Context Routing +Use the `@filename` (or file link) rules below to load *only* essential context into the cognitive window when instructed for a particular task: + +### Design & Frontend +For UI layout, responsive tokens, coloring, and animations, consult: +▶️ @.agents/rules/aegis-design.md +▶️ @.agents/skills/nextjs-ui/SKILL.md + +### Backend & Database +For server actions, Zod schemas, error handling, and data hydration, consult: +▶️ @.agents/skills/prisma-backend/SKILL.md + +### Core Architecture & Ralph Loop Context +To understand what exists and what is being built right now, ALWAYS review: +▶️ @docs/PRD.md +▶️ @docs/prompt.md + +## 3. Strict Prohibitions +- NEVER use generic or vague commit messages. +- Do NOT generate inline CSS when a Tailwind v4 utility exists. +- Do NOT write SQL raw strings where Prisma client methods can explicitly perform the query. + From 0f62fb2d94f3bbe8426e805c432ce6067642b912 Mon Sep 17 00:00:00 2001 From: Emiya Kiritsugu Date: Tue, 31 Mar 2026 17:04:47 -0300 Subject: [PATCH 2/4] docs: establish aegis design and git commit standard rules --- .agents/rules/aegis-design.md | 13 +++++++++++++ .agents/rules/git-commits.md | 16 ++++++++++++++++ 2 files changed, 29 insertions(+) create mode 100644 .agents/rules/aegis-design.md create mode 100644 .agents/rules/git-commits.md diff --git a/.agents/rules/aegis-design.md b/.agents/rules/aegis-design.md new file mode 100644 index 00000000..56fcca4f --- /dev/null +++ b/.agents/rules/aegis-design.md @@ -0,0 +1,13 @@ +# Aegis OS Design Guidelines + +## Core Identity +Aegis OS is a premium dark-mode application. The visual language conveys modern, high-performance, and secure fitness operations. +- **Electric Cyan/Blue accents:** Used for primary CTAs and active states. +- **Deep Blacks/Grays:** Used for background and surface elevation. +- **Glassmorphism:** Subdued blurs with subtle borders for cards and nav. + +## Rules +- When generating React components, always default to a dark background string like `bg-slate-950` or `bg-neutral-900`. +- Use Framer Motion or Tailwind's `transition-all` with custom durations (`duration-300` or `duration-500`) for all state changes (hover, focus, active). +- Never use plain browser default colors (`blue-500`) without intentional context. Rely on the defined custom tokens in CSS or carefully curated Tailwind shades (e.g., `cyan-400` to `blue-500` gradients). +- For forms and inputs, focus rings should be glowing and distinct. diff --git a/.agents/rules/git-commits.md b/.agents/rules/git-commits.md new file mode 100644 index 00000000..28970c92 --- /dev/null +++ b/.agents/rules/git-commits.md @@ -0,0 +1,16 @@ +# Git Workflow & Atomic Commit Rules + +## 1. Commit Prefix Standard +All agents and developers MUST use standard semantic prefixes: +- `feat:` for a new feature implementation or enhancement. +- `fix:` for fixing a bug or regression. +- `ui:` for design, CSS, or visual markup that doesn't alter logic. +- `docs:` for updates to PRD, skills, rules, README, or markdown logs. +- `refactor:` for restructuring code without functional changes. +- `chore:` for updating dependencies, build scripts, or configurations. +- `test:` for creating or modifying automated tests. + +## 2. Atomic Commits +- You must make **atomic commits**. Never bundle multiple disparate changes across unrelated components into a single commit. +- After successfully resolving a task block, verify the changes and commit it immediately with a descriptive message. +- If you finish `aegis-design.md`, commit it. If you finish `SKILLS.md`, commit it separately. This prevents massive diffs and ensures reliable rollbacks. From f364f7b9710646fd006272f034b0b9d3f778aade Mon Sep 17 00:00:00 2001 From: Emiya Kiritsugu Date: Tue, 31 Mar 2026 17:05:26 -0300 Subject: [PATCH 3/4] docs: establish modular nextjs and prisma skills --- .agents/skills/nextjs-ui/SKILL.md | 26 ++++++++++++++++++++++++++ .agents/skills/prisma-backend/SKILL.md | 22 ++++++++++++++++++++++ 2 files changed, 48 insertions(+) create mode 100644 .agents/skills/nextjs-ui/SKILL.md create mode 100644 .agents/skills/prisma-backend/SKILL.md diff --git a/.agents/skills/nextjs-ui/SKILL.md b/.agents/skills/nextjs-ui/SKILL.md new file mode 100644 index 00000000..ad7be9f8 --- /dev/null +++ b/.agents/skills/nextjs-ui/SKILL.md @@ -0,0 +1,26 @@ +# Next.js UI Engineering + +## Scope +This skill defines the architectural rules for writing components, pages, and layouts in the Next.js 15 (App Router) environment for the frontend of Aegis Fitness OS. + +## 1. Component Boundaries +- The project default is `Server Components`. +- You MUST explicitly include `"use client";` at the exact top of the file *only* if the component requires: + - `useState`, `useEffect`, `useRef`, or `useContext` + - Browser APIs (`window`, `document`) + - Event listeners (`onClick`, `onChange`) +- Whenever possible, fetch data on the server and pass it down as props to client components to reduce client-side JavaScript payloads. + +## 2. Tailwind V4 & Styling +- This project utilizes Tailwind CSS v4. Standard Tailwind v3 arbitrary values may require testing. +- Rely on modern spacing, fluid typography scaling, and Grid/Flex layouts. Never use float or legacy tabular layouts. +- **Glassmorphism:** To create our premium cards, combine background color opacity with backdrop-blur. + Example: `bg-slate-900/60 backdrop-blur-md border border-slate-800`. +- **Micro-Animations:** Enhance interactivity using the `group` class and transition utilities. + Example: `group-hover:translate-x-1 transition-all duration-300 ease-in-out`. +- Refer to ▶️ @.agents/rules/aegis-design.md before generating complex color palettes. + +## 3. Form Handling +- For input states and validations, use standard React-hook-form bindings gracefully tied to Zod validation states. +- Always display explicit error messages below the input fields in a subtle `text-red-400`. +- Icons should utilize `lucide-react`. Ensure appropriate strokewidth and sizing matching the font scaling. diff --git a/.agents/skills/prisma-backend/SKILL.md b/.agents/skills/prisma-backend/SKILL.md new file mode 100644 index 00000000..43b98822 --- /dev/null +++ b/.agents/skills/prisma-backend/SKILL.md @@ -0,0 +1,22 @@ +# Backend & Prisma Configuration + +## Scope +This skill outlines the standard rules for writing Server Actions, API routes, database integrations, and Zod parsers for the Aegis Fitness OS platform. + +## 1. Safety and Stability +- Always ensure Server Actions include `'use server';` exactly at the top of the file. +- All incoming payloads must be validated against a pre-established `zod` schema before ANY database interaction occurs to prevent injection. +- Ensure that you utilize robust try-catch blocks to catch and log errors, returning typed `{ success: boolean, data?: any, error?: string }` responses rather than raw objects. + +## 2. Prisma Database Integration +- NEVER guess schema fields when querying Prisma. When in doubt, read the `prisma/schema.prisma` file directly or use the MCP Prisma tool to introspect the structure. +- Always use the `prisma` client wrapper (if one is set up) or generate a new Prisma Client instance avoiding memory leaks in development. +- Prioritize batch queries with `.findMany` and optimal `.select` clauses so we do not over-fetch relations or payload data. +- Opt to use `.count` rather than `.findMany().length` for pagination or metric sizing. + +## 3. Asynchrony +- Do not mix `.then().catch()` chains with `await`. Use proper `async/await` exclusively in Next.js Server Actions. +- Ensure `revalidatePath` and `revalidateTag` are used to proactively refresh cache keys after an active mutation operation (e.g. creating a new training log). + +## 4. MCP Rule +- Rely on the `Prisma MCP` to write complicated migrations rather than attempting to hand-write SQL. The MCP connection provides absolute confidence in production-grade queries. From 7961f75911124948f9e8829dcf0cf15017ed9eab Mon Sep 17 00:00:00 2001 From: Emiya Kiritsugu Date: Tue, 31 Mar 2026 17:06:12 -0300 Subject: [PATCH 4/4] docs: establish the stateless execution loop files --- docs/PRD.md | 32 ++++++++++++++++++++++++++++++++ docs/friction.log | 6 ++++++ docs/progress.txt | 5 +++++ docs/prompt.md | 18 ++++++++++++++++++ 4 files changed, 61 insertions(+) create mode 100644 docs/PRD.md create mode 100644 docs/friction.log create mode 100644 docs/progress.txt create mode 100644 docs/prompt.md diff --git a/docs/PRD.md b/docs/PRD.md new file mode 100644 index 00000000..fbee4b0e --- /dev/null +++ b/docs/PRD.md @@ -0,0 +1,32 @@ +# Aegis OS Product Requirements Document + +## 1. Problem Definition +The current physical education application requires a modern, stable, secure management UI that handles user authentication, student analytics, workout routines, and gamified progress. + +## 2. Core Value Pillars +- **Security & Authorization:** Role-based access exclusively controlling Manager vs. Student routes. Use Zod parsing + Supabase Row Level Security logic. +- **Premium User Experience:** High-visibility analytics with dark-mode aesthetic (electric blue accents). Fast client navigation leveraging React transitions and Server Components. +- **Gamification Mechanics:** Tracking student streaks, leveling formulas based on training, and showing metric progression across months. + +## 3. Product Roadmap +The execution is structured into explicit phases: + +### Phase 1: Authentication & Layout Scaffold [DONE] +- Integrate Clerk or Supabase Auth. +- Create `/manager` layout and protected routes. +- Implement sidebar and main view topology matching `DESIGN.md`. + +### Phase 2: Core Data Engine (Students & Workouts) [IN PROGRESS] +- Prisma Schema integration (Alunos, Treinos). +- Standardized CRUD API boundaries (Server Actions). +- Dashboard data hydration for total enrollments and revenue. + +### Phase 3: Gamification & Engagement [TODO] +- Level computation algorithms. +- Progressive streak tracking. +- Client-side animations testing progression bars filling up. + +### Phase 4: Polish & Integration Deployment [TODO] +- End-to-End Vercel staging deploy. +- Vercel performance and Edge-node optimizations matching Vercel standard configs. +- AI telemetry tracing through Genkit setup. diff --git a/docs/friction.log b/docs/friction.log new file mode 100644 index 00000000..b338f351 --- /dev/null +++ b/docs/friction.log @@ -0,0 +1,6 @@ +# Aegis OS Friction Log + +## Document any systemic or repeated failures to ensure future agents do not hallucinate fixes. + +- **Vercel Build Edge functions:** Previously, Next.js Server Actions on Edge runtimes encountered failures attempting to use heavy Node drivers (like standard `pg`). Strict enforcement is required to use Prisma's edge compatibility or switch environments if encountering `unsupported driver` exceptions in CI. +- **Tailwind v4 vs v3 Configurations:** Custom arbitrary spacing logic is stricter under v4. Double-check utility class names before committing UI code relying heavily on arbitrary bracket assignments. diff --git a/docs/progress.txt b/docs/progress.txt new file mode 100644 index 00000000..4d3df636 --- /dev/null +++ b/docs/progress.txt @@ -0,0 +1,5 @@ +# Aegis OS Progress Ledger + +- 2026-03-31: Successfully scaffolded the core Antigravity Agentic Workspace architecture, instituting `AGENTS.md`, strict `.agents` standard routing, and stateless Ralph logs. +- 2026-03-30: Merged critical security fix branching restoring `pg` types safely into `main` without regressing the Premium Dark UI overhaul. +- [Prior log history aggregated here] diff --git a/docs/prompt.md b/docs/prompt.md new file mode 100644 index 00000000..8ee6d683 --- /dev/null +++ b/docs/prompt.md @@ -0,0 +1,18 @@ +# Aegis OS Agentic Prompt Template + +## Core Identity +You are an autonomous engineering system operating in the Aegis OS framework. Your sole purpose is to build highly constrained, reliable, and aesthetically immaculate systems matching `PRD.md`. + +## Execution Protocol +**1. Initial Discovery:** When tasked with a feature, ALWAYS read `PRD.md` to see its broader implications. Do not start coding isolated functions. +**2. Targeted Inclusion:** Read ONLY the specific `.agents/rules/` or `.agents/skills/` relevant to the problem. Do not ingest irrelevant logic. +**3. The Adversarial Review:** Before proposing file changes to the human principal, ask yourself: + - Did I properly use Tailwind v4, without defaulting to inline styles? + - Does the UI match the electric-cyan dark mode standard? + - DID I UPDATE `progress.txt` OR `friction.log` TO ENSURE CONTINUITY? + +If the answer to any is 'No', correct it first. + +## Prompting Format +All manual commands from the human will follow the ` ` standard. Example: +`[Feature] Scaffold the DashboardMetrics.tsx component using strictly standard Glassmorphism containers against the Prisma user count.`