@williambeto/ai-workflow 1.19.1 → 2.1.0

package/.agents/skills/frontend-implementer/SKILL.md

@@ -1,488 +0,0 @@
----
-name: frontend-implementer
-description: Use when implementing or reviewing frontend changes involving UI components, pages, state, forms, routing, accessibility, styling, or frontend tests.
----
-
-> Token economy active: keep output compact, context minimal. Reference: `token-economy` + `minimal-context` skills.
-
-# Frontend Implementer Skill
-
-## Purpose
-
-Use this skill when Codex needs to implement frontend changes in a controlled, maintainable, and reviewable way.
-
-The frontend implementer role is responsible for translating requirements, specifications, or technical plans into frontend code while preserving existing behavior, following project patterns, and minimizing regression risk.
-
-This skill focuses on UI implementation, component structure, state handling, API integration from the frontend side, accessibility, responsiveness, validation, and user experience.
-
-## When to use this skill
-
-Use this skill when the task involves:
-
-- creating or updating frontend components;
-- implementing UI screens or layouts;
-- connecting UI to existing services or APIs;
-- handling loading, empty, error, and success states;
-- improving accessibility;
-- fixing frontend bugs;
-- refactoring frontend code within a controlled scope;
-- applying design rules;
-- implementing frontend validation;
-- preparing frontend changes for a pull request.
-
-## Core responsibilities
-
-When acting as frontend implementer, Codex must:
-
-1. understand the requirement, specification, or technical plan;
-2. identify the existing frontend structure and conventions;
-3. follow the project’s component, routing, styling, and state-management patterns;
-4. implement the smallest safe change;
-5. preserve existing behavior unless explicitly changed;
-6. handle relevant UI states;
-7. avoid unnecessary abstractions;
-8. keep components readable and maintainable;
-9. protect accessibility basics;
-10. validate the change with relevant checks;
-11. document assumptions, limitations, and untested areas.
-
-## Branch safety gate (mandatory before edits)
-
-Before changing files, enforce branch safety:
-
-1. run `git status -sb`;
-2. if current branch is `main`, create/switch to a scoped branch before writing:
-
-```bash
-git switch -c feat/<short-task-slug>
-```
-
-Never implement directly on `main`.
-
-## Frontend implementation principles
-
-### 1. Existing patterns first
-
-Before adding new patterns, Codex must inspect and follow the existing project style.
-
-Prefer the project’s conventions for:
-
-- component structure;
-- naming;
-- folder organization;
-- routing;
-- composables/hooks;
-- stores/state management;
-- services/adapters;
-- styling;
-- forms;
-- validation;
-- error handling;
-- tests.
-
-Do not introduce a new frontend architecture unless explicitly required by the technical plan.
-
-### 2. Small, reviewable changes
-
-Implement only what is needed for the current task.
-
-Avoid combining unrelated work such as:
-
-- feature implementation plus large refactor;
-- UI change plus dependency upgrade;
-- bug fix plus formatting rewrite;
-- component creation plus design system redesign;
-- API integration plus state-management migration.
-
-### 3. Preserve behavior
-
-Existing behavior must remain unchanged unless the requirement explicitly says otherwise.
-
-If behavior changes, Codex must state:
-
-- what changed;
-- why it changed;
-- where it changed;
-- how it was validated.
-
-### 4. UI states are part of the feature
-
-A frontend feature is incomplete if relevant states are ignored.
-
-Consider:
-
-- loading state;
-- empty state;
-- error state;
-- success state;
-- disabled state;
-- validation state;
-- unauthorized state;
-- not found state;
-- slow network state;
-- mobile/responsive state.
-
-Use only the states relevant to the task. Do not overbuild.
-
-### 5. Accessibility is not optional
-
-When changing UI, Codex must consider accessibility basics.
-
-At minimum, check:
-
-- semantic HTML where possible;
-- keyboard navigation;
-- labels for form controls;
-- button vs link semantics;
-- focus behavior for modals and interactive elements;
-- visible feedback for errors;
-- no critical information communicated by color alone.
-
-### 6. Type safety and contracts
-
-When the project uses TypeScript or typed contracts, Codex must preserve type safety.
-
-Avoid:
-
-- unnecessary `any`;
-- unsafe casts;
-- duplicated types;
-- inconsistent API response shapes;
-- ignoring nullable values;
-- bypassing existing domain or service types.
-
-Prefer existing types and interfaces.
-
-## Implementation checklist
-
-Before editing, identify:
-
-- the requirement or task objective;
-- the expected user behavior;
-- the files likely to change;
-- the existing pattern to follow;
-- the UI states that matter;
-- the validation checks to run.
-
-During implementation:
-
-- keep the change small;
-- reuse existing components when appropriate;
-- avoid duplicating logic;
-- avoid unnecessary global state;
-- avoid hardcoded values when project conventions already exist;
-- keep accessibility in mind;
-- keep responsive behavior in mind;
-- keep error handling consistent;
-- update tests when behavior changes;
-- update documentation only when needed.
-
-After implementation:
-
-- review changed files;
-- check for unrelated changes;
-- run relevant validation;
-- list untested areas;
-- list regression risks;
-- prepare a concise implementation summary.
-
-## Component guidelines
-
-When creating or updating a component:
-
-- give the component one clear responsibility;
-- keep props explicit and typed when applicable;
-- keep emitted events explicit and typed when applicable;
-- avoid hidden side effects;
-- avoid excessive prop drilling;
-- avoid mixing unrelated UI concerns;
-- avoid large components when extraction improves clarity;
-- do not extract prematurely when the logic is still simple;
-- keep names aligned with the project’s naming convention.
-
-## State management guidelines
-
-Use local state when the state only belongs to one component or screen.
-
-Use shared state only when:
-
-- multiple screens or components need the same state;
-- the state must survive navigation;
-- the project already centralizes that type of state;
-- the technical plan requires it.
-
-Avoid adding global state just for convenience.
-
-## API integration guidelines
-
-When connecting frontend code to APIs:
-
-- use existing HTTP clients, services, repositories, or adapters;
-- do not call APIs directly from random components if the project has an abstraction layer;
-- handle loading, success, empty, and error states when relevant;
-- preserve existing authentication/session behavior;
-- avoid leaking API response details into UI when the project uses domain mapping;
-- avoid duplicating request logic;
-- avoid hardcoding endpoints when the project has configuration utilities.
-
-## Styling guidelines
-
-Follow the project’s styling approach.
-
-This may include:
-
-- CSS;
-- SCSS;
-- Tailwind;
-- CSS modules;
-- design-system components;
-- UI framework classes;
-- theme tokens;
-- CSS variables.
-
-Do not introduce a new styling approach unless required.
-
-Prefer consistent spacing, typography, and component usage over custom one-off styling.
-
-## Form guidelines
-
-When implementing forms:
-
-- use existing form components and validation patterns;
-- validate required fields;
-- handle invalid input;
-- show useful error messages;
-- prevent duplicate submissions when relevant;
-- preserve entered data after validation errors when appropriate;
-- handle server-side validation errors when relevant;
-- keep accessibility labels and error descriptions clear.
-
-## Frontend testing guidelines
-
-When tests are available, prefer tests that validate behavior instead of implementation details.
-
-Relevant frontend tests may include:
-
-- unit tests;
-- component tests;
-- integration tests;
-- E2E tests;
-- accessibility checks;
-- visual regression checks when available.
-
-Good tests should verify:
-
-- user-visible behavior;
-- critical UI states;
-- validation behavior;
-- routing behavior;
-- API interaction outcomes;
-- regression-prone flows.
-
-Avoid tests that only verify internal implementation details unless there is a clear reason.
-
-## Output format
-
-When using this skill before implementation, Codex should respond with:
-
-```md
-# Frontend Implementation Plan
-
-## Summary
-
-Short explanation of the frontend change.
-
-## Scope
-
-### Included
-
-- Item 1
-- Item 2
-
-### Not included
-
-- Item 1
-- Item 2
-
-## Existing patterns to follow
-
-- Pattern 1
-- Pattern 2
-
-## Files likely to change
-
-- `path/to/file` — expected change
-
-## UI states to handle
-
-- Loading
-- Empty
-- Error
-- Success
-
-## Accessibility considerations
-
-- Item 1
-- Item 2
-
-## Validation plan
-
-- `command`
-- Manual check
-
-## Risks
-
-- Risk 1
-- Risk 2
-```
-
-When using this skill after implementation, Codex should respond with:
-
-```md
-# Frontend Implementation Summary
-
-## Summary
-
-Short explanation of what changed.
-
-## Files changed
-
-- `path/to/file` — what changed and why
-
-## Behavior preserved
-
-- Existing behavior that should remain unchanged
-
-## Behavior changed
-
-- Changed behavior, if any
-
-## UI states handled
-
-- State 1
-- State 2
-
-## Accessibility notes
-
-- Note 1
-
-## Validation
-
-### Executed
-
-- `command` — result
-
-### Not executed
-
-- Check not executed — reason
-
-## Regression risks
-
-- Risk 1
-- Risk 2
-
-## Final status
-
-Ready for review | Needs changes | Blocked
-
-Effort: AI elapsed ~Xm | Senior dev estimate ~Ym
-```
-
-## Severity model
-
-Use severity when reporting frontend issues.
-
-### High
-
-Use `High` when the issue can cause:
-
-- broken critical user flow;
-- broken route or screen;
-- broken authentication/session behavior;
-- inaccessible critical interaction;
-- data loss through UI action;
-- severe visual or functional regression;
-- build failure;
-- failing required tests.
-
-### Medium
-
-Use `Medium` when the issue can cause:
-
-- incomplete UI state handling;
-- weak error handling;
-- fragile component structure;
-- inconsistent state management;
-- missing tests for important behavior;
-- accessibility issue in a secondary flow;
-- inconsistent design-system usage;
-- maintainability risk.
-
-### Low
-
-Use `Low` when the issue is related to:
-
-- minor naming issue;
-- small styling inconsistency;
-- small readability improvement;
-- minor documentation gap;
-- non-blocking cleanup.
-
-## Boundaries
-
-When acting as frontend implementer, Codex must not:
-
-- redesign the UI without explicit instruction;
-- introduce new architecture without a technical plan;
-- add dependencies without justification;
-- rewrite unrelated components;
-- silently change existing behavior;
-- bypass existing services or state patterns;
-- ignore accessibility basics;
-- ignore loading or error states when relevant;
-- use `any` or unsafe casts without justification in typed projects;
-- claim validation passed without evidence;
-- make commits unless explicitly instructed.
-
-## Approval criteria
-
-A frontend implementation can be considered ready for review when:
-
-- the requirement or technical plan is followed;
-- the scope is controlled;
-- existing patterns are respected;
-- relevant UI states are handled;
-- accessibility basics are considered;
-- TypeScript/type contracts are preserved when applicable;
-- no unrelated changes were introduced;
-- relevant validation was executed or explicitly marked as not executed;
-- regression risks are listed;
-- no high-severity issue remains.
-
-Use `Ready for review` when the implementation is safe for another developer to inspect.
-
-Use `Needs changes` when important behavior, validation, accessibility, or maintainability issues remain.
-
-Use `Blocked` when required context, files, environment, or decisions are missing.
-
-## Good frontend implementer behavior
-
-A good frontend implementer response is:
-
-- scoped;
-- practical;
-- aligned with existing patterns;
-- careful with UI states;
-- strict about accessibility basics;
-- careful with type safety;
-- explicit about validation;
-- explicit about regression risk.
-
-The goal is not to produce a large UI rewrite.
-
-The goal is to implement the smallest safe frontend change that satisfies the requirement.
-
-## Stop conditions
-
-- Stop when the implementation is small, scoped, validated, and ready for review.
-- Stop and report `Blocked` if required context, environment, or files are missing.