Imported from xasanovdev/learnOS-frontend (
AGENTS.md). Install upstream withnpx skills add xasanovdev/learnOS-frontend. Copyright stays with the author.
This is NOT the Next.js you know
This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in node_modules/next/dist/docs/ before writing any code. Heed deprecation notices.
Agent Instructions
Project Context
This is the learnOS frontend: a Next.js App Router application for a focused YouTube learning workspace. The app uses Next 16.2.9, React 19.2.4, TypeScript strict mode, Tailwind CSS v4, shadcn/Radix-style UI primitives, SWR, react-hook-form, zod, and lucide-react icons.
Primary paths:
app/: App Router routing only: route groups, route segments, layouts, pages, loading/error/not-found files, route handlers, and global styles.features/: business/domain logic, feature components, feature hooks, services, schemas, types, and feature-local utilities.components/: shared UI only. Keep this business-neutral.components/ui/: shadcn-style primitives. Prefer extending these before adding one-off controls.components/shared/: generic shared UI pieces such as the brand logo and shimmer primitive.lib/: infrastructure and generic helpers, including API fetch behavior inlib/api/.hooks/: generic app-wide hooks only. Feature hooks belong infeatures/*/hooks/.proxy.ts: Next 16 Proxy for dashboard auth redirects. This is not legacy Middleware.
There is intentionally no src/ directory. Use the root-level folders above.
Before Editing
- Analyze the available skills first, then use the smallest relevant set. If a skill applies, read its
SKILL.mdcompletely before acting and follow its workflow. - Read the local Next docs for the API or convention you are touching. Good starting points:
node_modules/next/dist/docs/01-app/01-getting-started/02-project-structure.mdnode_modules/next/dist/docs/01-app/01-getting-started/05-server-and-client-components.mdnode_modules/next/dist/docs/01-app/01-getting-started/15-route-handlers.mdnode_modules/next/dist/docs/01-app/01-getting-started/16-proxy.md
- Inspect nearby code and follow the local pattern before introducing a new abstraction.
- Keep changes narrowly scoped to the requested behavior. Do not refactor unrelated files.
- Do not add dependencies or change lockfiles unless the task genuinely requires it.
Agent skills
Issue tracker
Issues, PRDs, and implementation slices live in GitHub Issues for xasanovdev/learnOS-frontend. Use gh from the repository root so it infers the repository from git remote -v.
Triage labels
Use the default canonical triage state labels: needs-triage, needs-info, ready-for-agent, ready-for-human, and wontfix. Every triaged issue should carry exactly one state label and exactly one category label such as bug or enhancement. AFK-ready work uses ready-for-agent; work requiring human judgment uses ready-for-human.
Domain docs
This is a single-context repo. Read root CONTEXT.md and relevant docs/adr/ files when they exist; proceed silently when they do not. Use established domain vocabulary in issue titles, tests, implementation notes, and review findings. Surface conflicts with existing ADRs instead of silently overriding them.
Engineering skill package
The engineering skill package is vendored from addyosmani/agent-skills without content changes:
- Skill workflows live in
.agents/skills/<skill-name>/SKILL.mdand are discovered automatically. - Shared skill checklists live in
.agents/references/. - Keep these files synchronized with the upstream clone by copying them again; do not maintain project-specific edits inside the vendored files.
Use using-agent-skills to select the smallest relevant workflow for a task. The skill package supplements the project-specific rules in this file; it does not override them.
Specialist agents
Project-scoped Codex custom agents live at:
.codex/agents/code-reviewer.toml.codex/agents/security-auditor.toml.codex/agents/test-engineer.toml.codex/agents/web-performance-auditor.toml
Each manifest is a thin adapter over the exact upstream persona prompt in .agents/*.md, keeping the vendored prompt as the source of truth. Codex discovers these manifests in trusted projects. Spawn or parallelize them only when the user explicitly requests delegation, subagents, or parallel agent work; the primary agent owns orchestration and final synthesis.
Skill Routing
- Use
zoom-outwhen the code area is unfamiliar and you need a map of modules, callers, and domain terms before editing. - Use
diagnosefor bugs, broken behavior, thrown errors, or performance regressions. Build a fast repro loop before fixing. - Use
tddwhen the user asks for test-first work or when a change has meaningful behavioral risk. Add one behavior test at a time and keep tests on public interfaces. - Use
frontend-designfor new or substantially changed UI. Match the product context and existing design system rather than producing generic layouts. - Use
react-doctorafter React changes when practical, especially after feature work, bug fixes, or reviews. - Use
improve-codebase-architecturefor refactor requests, testability problems, shallow modules, or broad architecture review. - Use
to-prd,to-issues, andtriageonly for product planning and issue-tracker workflows; follow the tracker and label conventions in this file.
Architecture Rules
- Use this mental model:
app/is for routing,features/is for business logic,components/is for shared UI, andlib/is for infrastructure. - Keep
app/thin. Route files should compose feature components, unwrapparams/searchParams, define metadata, and handle route-level redirects only. - Use route groups such as
(marketing),(auth), and(workspace)to separate layouts without changing URLs. - Route-private
_componentsfolders are allowed only for code that is genuinely specific to one route. Domain-level code belongs infeatures/. - Default to Server Components in
app/and feature components. Add"use client"only when the file needs state, effects, event handlers, browser APIs, SWR, or client hooks. - Keep client boundaries small. A file marked
"use client"pulls its imports into the client bundle, so avoid placing large static layouts or data-only helpers behind that boundary. - Use App Router file conventions. A route is exposed by
page.tsxorroute.ts; colocated helper files are fine, but do not putroute.tsat the same route segment level aspage.tsx. - Use
next/linkfor internal navigation andnext/navigationhooks only in Client Components. - Treat
proxy.tsas an optimistic redirect layer only. Do not put slow data fetching, full session validation, or business logic there. - Keep shared domain types close to the code that consumes them until they are reused across multiple modules.
- Use predictable feature subfolders:
components/,hooks/,services/,schemas/,types/, andutils/when those responsibilities exist. - Use clear suffixes for non-component modules:
.service.ts,.schema.ts,.types.ts,.server.ts, and.client.tsxwhen a boundary needs to be explicit.
Data, Auth, And API Calls
- Browser-side API calls should go through
fetcherinlib/api/fetcher.tsso credentials, JSON headers,401refresh,204, and empty responses are handled consistently. - Feature API functions belong in
features/*/services/*.service.ts; feature SWR hooks belong infeatures/*/hooks/. - Reusable hooks should accept route params/search params as arguments. Do not read
useSearchParams()or route params inside a reusable feature hook unless the hook is explicitly route-specific. - Preserve the existing rewrite model in
next.config.ts: frontend paths such as/auth/*,/rooms/*, and/videos/*are forwarded toNEXT_PUBLIC_API_URL. - Use SWR for client-loaded remote data when following existing dashboard/auth patterns.
- Validate user input with zod and surface form errors through the existing form/UI components.
- Never expose secrets to the client. Only
NEXT_PUBLIC_*environment variables are safe for browser code.
TypeScript And React Quality
- Keep
strictTypeScript clean. Avoidany; prefer explicit domain types and narrow unions. - Prefer derived values with
useMemoonly when it avoids meaningful repeated work or clarifies state derivation. Do not memoize everything by default. - Keep async handlers explicit about loading, success, and failure states.
- Make invalid states hard to represent when practical, especially for request status, form state, and auth state.
- Keep components readable. If a component grows large, extract cohesive child components or helpers in the same feature area.
Component Structure And Refactoring
- Prefer clean, component-based file structure over large multi-component modules.
- Keep one main component per file. Small private helpers are fine, but extract meaningful UI sections into their own files once they have independent props, state, layout responsibility, or reuse potential.
- Use named exports for project components and helpers. Avoid default exports except where framework conventions require them, such as route pages and layouts.
- Preserve existing UI, styling, behavior, props, and TypeScript contracts during refactors. Do not mix structural cleanup with business-logic changes unless the user asks for both.
- Before a meaningful refactor, identify and communicate the proposed folder/file structure. Keep it feature-local and avoid creating excessive tiny files for trivial helpers.
- Put pure shared helper functions in a nearby
utils.tsor feature utility file. Do not hide business logic inside visual components when it can be named and tested separately. - Put loading, empty-state, and skeleton UI in a dedicated nearby skeleton/loading area when there are multiple variants or when the skeleton mirrors a full page layout. Feature-specific skeletons belong with their feature, not in
components/shared/. - Put small reusable feature UI pieces in a nearby
components/folder when a feature needs several shared controls or display components. - Keep shared UI primitives and business-neutral shared components in
components/; do not put feature-specific cards, forms, pages, modals, or data-aware UI there. - Add
"use client"only to files that need React hooks, event handlers, browser APIs, router/search param hooks, SWR, or other client-only behavior. Keep static presentational components as Server Component-compatible when possible. - Avoid circular imports. Shared UI may import utilities, but utilities should not import UI components.
- Keep imports clean after splitting files. Prefer
@/*aliases for cross-folder imports and relative imports only for tight feature-local neighbors.
Review Expectations
- In reviews and self-review, flag oversized components, mixed responsibilities, unnecessary client boundaries, duplicated skeleton markup, hidden business logic in UI files, and circular dependency risk.
- Treat refactor output as incomplete until lint and TypeScript pass, and run a build when routes, layouts, client/server boundaries, or Next conventions changed.
- When summarizing a refactor, list the changed files and the responsibility each file now owns.
Styling And UI
- Treat
features/landing/components/landing-page.tsxand its section components as the canonical visual reference for marketing and top-level product surfaces. - The active style is warm editorial-brutalist, not generic SaaS: soft paper background, strong ink outlines, restrained peach accent, and offset shadows for featured surfaces.
- Keep the primary palette anchored to:
- paper
#fffdf9 - ink
#0d0d0c - warm accent
#f4ded0 - accent text
#9d6550 - hover ink
#2a2927
- paper
- Use Tailwind v4 utilities and the CSS variables defined in
app/globals.css. - Use
cnfromlib/utils.tsfor conditional class names. - Reuse
components/uiprimitives for buttons, inputs, labels, fields, cards, separators, and OTP inputs. - Use lucide-react icons for actions when an icon improves scanability.
- Match the existing visual language: focused, study-oriented, editorial, tactile, responsive, and accessible.
- Prefer full-width section bands with constrained inner containers such as
max-w-7xl,max-w-6xl, ormax-w-5xl. Alternate between light paper sections, white framed sections, and dark ink sections rather than stacking identical cards. - Favor hard borders and square or lightly rounded frames for hero surfaces, cards, tiles, and mocks. Use offset shadow patterns like
shadow-[8px_8px_0_#0d0d0c]orshadow-[12px_12px_0_#0d0d0c]for featured blocks instead of soft floating-card styling. - Reserve pill rounding for navigational or CTA elements such as the header shell and primary action links. Do not apply large soft radii everywhere.
- Use backgrounds with atmosphere: warm top gradients, light grid textures, translucent white overlays, and dark sections with subtle borders. Avoid flat app-store gradients or purple/blue startup palettes.
- Typography should stay bold and compact with high-contrast headlines, normal tracking, and short uppercase eyebrow labels in the warm accent color. Do not introduce decorative display fonts that fight the existing mark and layout.
- Preserve the existing interaction pattern where chrome can shrink on scroll rather than disappear. For headers and persistent controls, prefer minimized, denser states over hiding important navigation.
- On mobile, collapse multi-column layouts into single-column stacks first, then into two-column grids only when content density still reads cleanly. Keep the same border/shadow language, but reduce offsets, padding, and decorative layers before removing structure entirely.
- When adapting desktop compositions for small screens, protect three things in order: readable headline width, comfortable tap targets, and intact framed surfaces. Do not let text wrap into awkward narrow columns or let offset-shadow decorations clip the viewport.
- Preserve keyboard accessibility, focus-visible styles, labels, semantic headings, and meaningful alt text.
- Check responsive behavior for new UI at mobile and desktop widths. Avoid text overlap, clipped controls, and layout shifts.
Verification
- Run the relevant
package.jsonscript after changes:npm run lintfor TypeScript/React/style safety.npm run buildwhen touching routing, Next config, server/client boundaries, or other build-sensitive code.
- For visual changes, run the dev server and inspect the affected routes in a browser.
- If verification cannot be run, state exactly why and what risk remains.
Git And File Hygiene
- Do not overwrite user changes. If the worktree is dirty, preserve unrelated edits.
- Do not edit generated files such as
next-env.d.tsor.next/**. - Keep imports tidy and use the
@/*path alias where it matches existing code. - Prefer small, reviewable commits or patches. Avoid broad formatting churn.
Beads Issue Tracker
This project uses bd (beads) for issue tracking. Run bd prime to see full workflow context and commands.
Quick Reference
bd ready # Find available work
bd show <id> # View issue details
bd update <id> --claim # Claim work
bd close <id> # Complete work
Rules
- Use
bdfor ALL task tracking — do NOT use TodoWrite, TaskCreate, or markdown TODO lists - Run
bd primefor detailed command reference and session close protocol - Use
bd rememberfor persistent knowledge — do NOT use MEMORY.md files - Before creating an issue in
bd, ensure the issue includes:- Acceptance criteria
- Steps to reproduce the problem or solve the task
- A list of files to review
Architecture in one line: issues live in a local Dolt DB; sync uses refs/dolt/data on your git remote; .beads/issues.jsonl is a passive export. See https://github.com/gastownhall/beads/blob/main/docs/SYNC_CONCEPTS.md for details and anti-patterns.
Session Completion
When ending a work session, you MUST complete ALL steps below. Work is NOT complete until git push succeeds.
MANDATORY WORKFLOW:
- File issues for remaining work - Create issues for anything that needs follow-up
- Run quality gates (if code changed) - Tests, linters, builds
- Update issue status - Close finished work, update in-progress items
- PUSH TO REMOTE - This is MANDATORY:
git pull --rebase git push git status # MUST show "up to date with origin" - Clean up - Clear stashes, prune remote branches
- Verify - All changes committed AND pushed
- Hand off - Provide context for next session
CRITICAL RULES:
- Work is NOT complete until
git pushsucceeds - NEVER stop before pushing - that leaves work stranded locally
- NEVER say "ready to push when you are" - YOU must push
- If push fails, resolve and retry until it succeeds
Beads Issue Tracker
Use Beads (bd) for durable task tracking in repositories that include it. Use the beads skill at .agents/skills/beads/SKILL.md (project install) or ~/.agents/skills/beads/SKILL.md (global install) for Beads workflow guidance, then use the bd CLI for issue operations.
Quick Reference
bd ready # Find available work
bd show <id> # View issue details
bd update <id> --claim # Claim work
bd close <id> # Complete work
bd prime # Refresh Beads context
Rules
- Use
bdfor all task tracking; do not create markdown TODO lists. - Run
bd primewhen Beads context is missing or stale. - Keep persistent project memory in Beads via
bd remember; do not create ad hoc memory files.
