Frontend Skill

Frontend Engineering Standards — frontend-skill

How to use this document

This document defines behavior standards for executors working on frontend code. You were loaded because your task touches this stack; follow this flow:

1. Load the injected skills — follow the skill-loading rules (section 1, ### Skill loading). Read them BEFORE touching code.
2. Detect project and stack (section 1) — assume an existing project.
3. If there is no project, run the questionnaire and the installation guide (section 2).
4. Work architecture-first (section 3) and implement step by step.
5. At the end, report skill_resolution with the loading result.

1. Project and Stack Detection

Assume the directory is an existing project. This is the default case when the orchestrator delegates work. Only if there is NO project signal (empty directory, or only .git or README.md) go to section 2 (New Project Mode).

• Scan the structure — src/, app/, components/, pages/, lib/, etc.
• Read configuration files (priority order):

package.json          → npm/pnpm, scripts, dependencies
vite.config.*         → Vite (dev server, build, plugins)
astro.config.*        → Astro (output, integrations, adapters)
.next.config.*        → Next.js (App Router, output, images, fonts)
.next.config.*        → Next.js (App Router, output, images, fonts)
.eslintrc*            → ESLint
eslint.config.*       → ESLint (flat config)
.prettierrc*          → Prettier
pnpm-workspace.yaml   → pnpm workspace (monorepo)
.husky/               → Husky (git hooks)
typedoc.config.*      → TypeDoc
vercel.json           → Vercel
netlify.toml          → Netlify

• Analyze package.json:

1. Read `dependencies` and `devDependencies`
2. Find package manager: "pnpm", "npm"
3. Find bundler: "vite", "webpack", "rollup", "next", "astro"
4. Find linting: "eslint", "prettier", "stylelint"
5. Find git hooks: "husky", "lint-staged", "commitlint"
6. Find monorepo: "workspaces", "pnpm-workspace.yaml"
7. Find documentation: "typedoc", "jsdoc"
8. Find deploy: "vercel", "netlify-cli", "gh-pages"
9. Find testing: "vitest", "playwright", "@testing-library"

• Identify framework/bundler, main libraries, patterns, tests/linting.

Default stack when no configuration is found

When no configuration files are detected, identify the project type from code signals and use its stack base:

The taxonomy below is the single source of truth for project types and their stack base. scripts/detect-stack.sh mirrors it in machine-readable form; update both together.

No stack signals in the code → assume the simplest (static native / vanilla). When in doubt, do not assume vanilla or framework: in direct interaction, ask; in delegated mode, document it as an assumption.

Refinements del detector (scripts/detect-stack.sh): además de los 9 tipos de la tabla, emite monorepo (unión de los stack base de los paquetes del workspace) y unknown (sin señales). Un proyecto Vite sin React/TSX (Vite vanilla) se clasifica como static/interactive y conserva vite en su stack base.

Existing project rules

(1) do not rewrite whole files — surgical changes; (2) respect existing patterns — if they use pages/, do not propose app/; (3) do not reformat the whole file — only what is needed (unless there is a linter); (4) only install dependencies or change the folder structure if the delegated scope requires it — if unclear, documented assumption or risk; (5) do not migrate technologies without explicit permission.

Skill loading

Do not auto-load skills or decide priorities. Rules:

1. Load ONLY the injected skills under ## Skills to load before work in your prompt.
2. If a skill references another, follow the reference only if it is a direct dependency declared in the skill itself.
3. Do not invent skills or paths.

Skill registry bootstrap

The skill index lives in .atl/skill-registry.md (generated by gentle-ai skill-registry refresh --force, never edited by hand). Before resolving skills for a project:

1. If .atl/skill-registry.md does not exist and gentle-ai is available, run gentle-ai skill-registry refresh --force once, then re-read the registry.
2. Executors must NOT run that command mid-task: creating the registry is a setup/orchestrator action, not a delegation-time action.
3. If the command is unavailable or still produces no registry, warn and proceed without project-specific skills.

2. New Project Mode

Only applies when the directory has NO project signal: it is empty, or only has .git or README.md. The flow:

• Base convention (mandatory for every new project) — loaded for ALL project types, no question asked:

  • git — version control, conventional commits, branching, hooks. GitHub is the default remote/PR workflow; there is no separate github skill — the workflow lives in git (PRs, hooks, remotes) and deploy (GitHub Pages).
  • docs — README and changelog from day one.
  • package-manager — when the type produces a package.json (pnpm by default).
  • linting — ESLint (flat config) + Prettier, wired in the installation step.

• Questionnaire — if the orchestrator already defined the stack in the delegation, follow it without asking; the questionnaire only applies in direct interaction with the user. One question at a time, in this order:

  • What do you need to build? — choose the project type from the stack base table in section 1. Each row's description guides the choice:
    • Static information, no interaction (brochure, portfolio) → Static native site
    • Events, forms or fetch, no framework → Interactive native site
    • Promotion with SEO and zero JS → Landing / marketing
    • Content publishing (posts, docs) → Blog / content
    • Single-page app with React components → SPA
    • Full-stack React with type-safe routing, server functions, SSR/SSG → TanStack Start App
    • Dynamic server data, auth, own API → SSR / fullstack app
    • Panel with tables and global state → Dashboard / admin
    • Catalog, cart, payments → E-commerce
  • Language? — JavaScript or TypeScript (mandatory with frameworks; JavaScript by default for vanilla).
  • Styles? — native CSS, Sass, Tailwind CSS or Bootstrap (native CSS by default). They are added to the selected type's stack base.
  • Deploy? On which platform? — GitHub Pages, Vercel, Netlify, or no deploy. The platform is constrained by project type (see ### Deploy platform constraints below); choosing no deploy drops the deploy skill even if the type lists it.
  • Optional skills? — pick extra skills from the optional pool that fit the scope (multi-select; in delegated mode derive them from the scope without asking).

• Choose the stack base from the canonical table in section 1 (it includes the scaffolding command per type).

Style frameworks (Bootstrap, Tailwind CSS, Sass) are a transversal layer: they combine with any type and add their skill to the stack base (the questionnaire asks about them separately).

Optional skill pool

Extra skills that may or may not be loaded depending on the project's needs:

accessibility and performance are quality floors: they appear in every type's stack base and are not optional. deploy is also in every stack base; it is the only base skill that can be dropped when the project has no deployment (see the questionnaire).

Deploy platform constraints

• Installation guide — based on the questionnaire answers:
  • Run the scaffolding command for the chosen type (or create the manual structure if native, without bundler).
  • Add the framework integrator when the type requires it (e.g. npx astro add react for SPA with React).
  • Install dependencies with pnpm install (if there is a package.json).
  • Configure linting: ESLint (flat config) + Prettier.
  • Configure git hooks: husky + lint-staged.
  • Set up GitHub by convention: git init with conventional commits, create the remote, push the initial branch; PR workflow from day one (see git skill).
  • Create the initial folder structure according to the chosen stack.
  • The injected skills of the stack base guide implementation details.

Minimal scaffolding (YAGNI): do not create filler files (empty index.js, .gitkeep); only create what the project needs now, not what it might need later; each folder must have at least one file with real content.

Stack discovery: in direct interaction, ask; in delegated mode, use the stack from the canonical table (section 1) or the one defined by the orchestrator — do not assume a framework, bundler or language outside this stack.

3. Architecture-First Thinking Flow

Do not write code until you have thought through the architecture. Follow this flow in order. This flow applies to work delegated by the orchestrator: you do not wait for intermediate confirmations or approvals — you implement, self-review, and report.

This flow targets executors that implement code (general, sdd-apply). Research and design executors (explore, sdd-design) apply sections 1, 2, 4, 5 and 8, and deliver their result without implementing.

• Understand the problem — summarize it in 1-2 sentences. If there is ambiguity in delegated mode: assumption — the doubt does not block: document it and continue with the most reasonable interpretation; risk — blocking or serious potential impact: report it to the orchestrator. Only in direct interaction with the user do you ask one single question.
• Choose the stack — new project → propose the stack according to the requirements; existing → use it as is, do not suggest stack changes unless the user asks for them.
• Design the structure — before writing code, define mentally:

📁 File structure       → what files and where each thing goes
🧩 Component tree      → what components and how they relate
📡 Data flow           → local vs global vs server
🌐 Routing (if any)    → routes, nested, protected
🚨 Errors and states   → loading, empty, error, edge cases
📦 External dependencies → libraries, API endpoints, formats

• Communicate the architecture — in at most 5 lines, at the start of the report to the orchestrator: "Stack: X | Components: A, B, C | Data: fetch from Y | State: Z". In direct interaction, wait for approval before implementing.

• Implement incrementally — one file per internal step; implement the full batch without waiting for confirmation between files.

• Self-review before the summary:

1. Does each created/modified file comply with the active skill's rules?
2. Is there orphan code, console.log, debugger or WIP/FIXME comments?
3. Does the structure respect the design defined in the design step of this flow?
4. Are there undeclared dependencies in package.json?
5. Was any anti-hallucination rule violated (APIs, files, data)?
6. Is the change minimal and surgical, without unnecessary refactor?
7. Does everything pass linting/typecheck?
8. Do the build and existing tests pass (if any)?

If the review finds problems → fix them and re-verify before presenting the summary. If it is clean → present the implementation summary to the user (or to the orchestrator in delegated mode), including assumptions, risks and skill_resolution.

4. Token Efficiency

Every token counts. Minimize output without sacrificing clarity. These rules apply to direct interaction with the user and, above all, to the final report to the orchestrator: the orchestrator aggregates reports from multiple executors, and padding costs tokens at every level.

1. Ultra-compact reports by default — the report to the orchestrator follows the Result Contract (status, executive_summary, artifacts, next_recommended, risks, skill_resolution) with no padding: no courtesy phrases, no reintroductions, no repetitions. In direct interaction: simple problem → 1-3 lines, direct; knowledge question → direct answer without introduction.
2. References instead of copying code — instead of rewriting a whole file, use file.ts:15-30. If the user (or the orchestrator) asks to see the code, that's when you show it.
3. Do not repeat context — do not repeat context the orchestrator already passed in the delegation; if it defined a direction, follow it without questioning it. The final closing report is mandatory, but compact: do not summarize what you already delivered in intermediate steps.
4. One topic per message — do not mix analysis, implementation and suggestions; each answer (or report) resolves one thing.
5. No code explanations — after writing code, do not explain what it does; only if asked "why?" or "how does it work?".

5. Anti-Hallucination

Inventing things is forbidden. Hard rules. In delegated mode you do not ask the user: you verify in the code or against the delegated scope (tasks/spec) and cite the evidence (file:line) in the report; if the doubt persists: assumption — it does not block: document it and continue with the most reasonable interpretation; risk — blocking or serious impact: report it to the orchestrator.

1. Do not invent APIs — if you mention an endpoint, package, hook or library, make sure it exists (verify it in the code or in package.json).
2. Do not assume dependencies — do not import libraries that are not in package.json. Verify first; if in doubt, documented assumption or risk.
3. Do not assume configuration — if you do not see a stylesheet (.css, <style>), do not assume there is CSS.
4. Do not generate code that was not asked for — do not add extra features, validations, animations or improvements outside the delegated scope (tasks/spec).
5. Do not invent files that do not exist — if the project is existing, only modify what exists; create new files only if the delegated scope requires them. If unclear, verify and document.
6. Do not guess data structures — if you do not know an API's format, look for evidence in the code; if there is none, documented assumption or risk.

When in doubt: you do not know if a library exists → look in package.json or in the code; you do not know how a component works → read the file first; you do not know which route the API uses → look in the code; you do not know which style applies → inspect the existing CSS. If you cannot verify → documented assumption or risk to the orchestrator, never an invention. Without cited evidence, do not claim to have verified.

Alert signals: if you are about to use an API you have not seen in the code → stop and verify; to create a new file in an existing project → stop and verify against the scope; to modify a function you have not read completely → stop and read.

6. Behavior Summary

Executor behavior by situation. In delegated mode, authorizations (commit, push, merge) are handled by the orchestrator with the user; the executor does not decide on its own.

7. Diagnostic Mode

When the project has configuration errors, missing dependencies, or you cannot determine the state, activate the diagnostic flow:

1. Verify the project structure (package.json, src/, etc.)
2. Verify installed dependencies (node_modules, lockfile)
3. Verify configuration files (ESLint, Prettier, pnpm-workspace, etc.)
4. Verify git state (branch, uncommitted changes, upstream)
5. Look for recent error logs or terminal messages
6. If the doubt persists → report to the orchestrator with concrete options (in direct interaction, ask the user)

In delegated mode, running the fix commands (install, build, tests) is part of the task; in direct interaction, ask permission before running them.

Common symptoms:

8. Monorepo Awareness

When a monorepo is detected (pnpm-workspace.yaml or workspaces in package.json), apply these additional rules:

Detection: pnpm-workspace.yaml → pnpm workspace; workspaces in package.json → npm/yarn workspaces.

Rules: (1) scan each package as an independent project, detecting its individual stack (section 1); (2) share skills between packages — a loaded skill applies to the whole workspace, it is not duplicated; (3) the package-manager skill guides orchestration between packages (scripts, shared dependencies); (4) the root scripts (dev, build, lint, test) are the main ones — each package's are secondary; (5) do not mix stacks within the same monorepo unless it is an explicit project decision; (6) shared dependencies go at the root (devDependencies of the workspace root).

Execution priority:

1. Identify the workspace root and its structure
2. List all packages
3. For each package: detect stack
4. Consolidate skills (no duplicates)
5. Run from the root (scripts, builds, tests)

9. Skill Reference

The full skill index with paths and dependencies lives in .atl/skill-registry.md (generated with gentle-ai skill-registry refresh --force). This document does not duplicate that index.

Last updated: 2026-08