Перевод: оболочка страницы на русском; тело навыка (SKILL.md) пока на английском — это исходные инструкции агента.

Large Admin Ia

Structure large admin apps via IA and CRUD stubs.

Метаданные навыка

Источник	Встроенный (установлен по умолчанию)
Путь	skills/web-development/large-admin-ia
Версия	1.0.0
Автор	VibeOS
Лицензия	MIT
Платформы	linux, macos, windows
Теги	admin, ia, cms, crud, nextjs, roles, permissions, web
Связанные навыки	internet-starter, cinematic-web, site-map-crawl, browser-e2e, page-agent

Справка: полный SKILL.md

к сведению

Ниже полное определение навыка, которое VibeOS загружает при активации. Это инструкции, которые видит агент.

Large Admin IA Skill

Plan and scaffold a separate large management / admin app: entities, information architecture, roles, permissions, and CRUD stubs — not a marketing landing and not an extension of the VibeOS dashboard.

Hard boundary. Customer CMS / ops consoles ship as their own Next (or existing target) app. Do not add routes under vibeos dashboard / web/src/pages for this work.

Optional NL in admin

After the separate admin app exists, you may embed optional-skill page-agent (vibeos skills install official/web-development/page-agent) so end-users drive that app’s UI with natural language. Embed only in the customer admin app — never in the VibeOS dashboard. page-agent is in-page (client DOM); it is not VibeOS browser automation (browser-e2e / browser tools).

When to Use

• User wants a multi-entity admin, CMS, or ops console (list/detail/forms)
• Need screens, nav tree, roles, and a permissions matrix before coding
• After internet-starter (or an existing target dir) — never the VibeOS dashboard
• Verify smoke with browser-e2e / browser tools; map routes with site-map-crawl

Prerequisites

• Node.js 20+ and npm when scaffolding Next (terminal)
• Write access for entities.yaml, IA.md, and app stubs in the target app
• Backend from brief: Convex or FastAPI + SQL stubs — do not force one
• Browser tools for smoke: browser_navigate, browser_snapshot
• Templates under this skill: templates/, references/permissions-matrix.md

How to Run

1. Capture a short brief (domain, actors, must-have entities, backend preference).
2. Author entities.json from templates/entities.example.json (or YAML example).
3. Generate stubs in a separate out dir: python3 scripts/scaffold_admin.py --entities templates/entities.example.json --out ./admin-app Optional FastAPI in-memory CRUD (separate from VibeOS dashboard): python3 scripts/scaffold_admin.py --entities templates/entities.example.json --out ./admin-app --with-api That writes api/requirements.txt, api/app/main.py (/health + per-entity list/get/create/update/delete), and api/README.md (uvicorn on port 8000). Optional Convex schema + CRUD stubs (files only; no npm install): python3 scripts/scaffold_admin.py --entities templates/entities.example.json --out ./admin-app --with-convex That writes convex/schema.ts, convex/<slug>.ts (list / get / create / update / remove), convex/tsconfig.json, and convex/README.md (npx convex dev). Flags can combine: --with-api --with-convex. Optional page-agent NL stub (this admin only): python3 scripts/scaffold_admin.py --entities … --out ./admin-app --with-page-agent → components/PageAgentEmbed.tsx + PAGE_AGENT.md. Same flags via CLI: vibeos web scaffold admin ./admin --with-api --with-convex --with-page-agent.
4. Review generated IA.md + permissions.md; refine roles/screens by hand.
5. Wire a real data layer (Convex or FastAPI+SQL) — stubs are shells only. With --with-api, start from the generated FastAPI stub and replace the dict stores with a real database. With --with-convex, run npx convex dev and wire the Next stubs to the generated functions. With --with-page-agent, follow PAGE_AGENT.md (npm install page-agent, mount <PageAgentEmbed />, set NEXT_PUBLIC_PAGE_AGENT=1).
6. Checklist empty / error / loading on every primary screen; then browser-e2e.

If paths are unknown: search_files for large-admin-ia/.

Quick Reference

Artifact	Role
Brief	Scope, actors, backend choice (Convex | FastAPI+SQL)
entities.yaml	Entities, fields, relations
IA.md	Screens, nav tree, roles, state notes
Permissions matrix	role × entity × list/read/create/update/delete
App scaffold	Separate Next (or target dir) — not VibeOS dashboard
CRUD stubs	List, detail, form shells per entity

Tool	Use
read_file	Brief, templates, existing target code
patch	Write YAML/MD/stubs in the target app
terminal	Scaffold, install, npm run dev, API stubs
browser_navigate / browser_snapshot	Smoke key screens

Do	Don't
Separate customer admin app	Extend web/src/pages / vibeos dashboard
Choose backend from brief	Invent CMS core tools
Cover empty/error/loading	Ship list pages with no empty state

Procedure

1. Brief — Domain, primary jobs, roles (e.g. admin/editor/viewer), backend preference (Convex or FastAPI+SQL), and out-of-scope (no dashboard merge).
2. Entities — Copy templates/entities.example.yaml → project entities.yaml. Name entities, scalar fields, and relations (belongs_to / has_many).
3. IA — Copy templates/IA.example.md → IA.md. List screens, nav tree, role gates, and notes for empty / error / loading per major view.
4. Permissions — Fill the matrix in references/permissions-matrix.md (or a project copy). Mark allow/deny for list, read, create, update, delete.
5. Scaffold — New Next app via internet-starter / terminal, or use the user-named target directory. Refuse patches into VibeOS dashboard sources. Prefer scripts/scaffold_admin.py (optional --with-api / --with-convex).
6. Backend stubs — Per brief: Convex schema + queries/mutations stubs (--with-convex), or FastAPI routers + SQL models/migrations stubs (--with-api gives an in-memory FastAPI starting point). Keep stubs aligned to entities.
7. CRUD UI stubs — For each entity: list, detail, create/edit shells; nav from IA; gate actions by the matrix (hide or disable, don't only comment).
8. States checklist — Empty, error, and loading on every primary screen.
9. Smoke — terminal start app → browser_navigate + browser_snapshot on home, one list, one detail, one denied-role path if feasible. Optional: site-map-crawl for route inventory; browser-e2e for deeper flows.
10. Later (optional) — see Optional NL in admin (page-agent in this app only). Do not conflate with cinematic marketing sites (cinematic-web).

Pitfalls

• Zero new core CMS tools — use read_file, patch, terminal, browser tools.
• Never treat VibeOS dashboard / web/src/pages as the customer CMS shell.
• Do not force Convex or FastAPI; pick from the brief and stub only that path.
• Permissions without UI gates leave editors seeing admin actions — wire both.
• Skip empty/error/loading and lists look broken on day one.
• Marketing scroll landings belong to cinematic-web, not this skill.

Verification

• entities.yaml and IA.md exist in the target app (or agreed paths)
• Permissions matrix filled for every entity × role
• App is a separate scaffold/target — not vibeos dashboard
• CRUD stubs + nav match IA; backend stubs match brief choice
• Empty / error / loading checklist done for primary screens
• Browser smoke via browser_navigate + browser_snapshot (or browser-e2e)