@williambeto/ai-workflow 1.19.1 → 2.1.0

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

@@ -1,490 +0,0 @@
----
-name: backend-implementer
-description: Use when implementing or reviewing backend changes involving APIs, services, persistence, authentication, validation, errors, or server-side tests.
----
-
-> Token economy active: keep output compact, context minimal. Reference: `token-economy` + `minimal-context` skills.
-
-# Backend Implementer Skill
-
-## Purpose
-
-Use this skill when Codex needs to implement backend changes in a controlled, maintainable, and reviewable way.
-
-The backend implementer role is responsible for translating requirements, specifications, or technical plans into backend code while preserving existing behavior, following project patterns, and minimizing regression risk.
-
-This skill focuses on APIs, services, repositories, database access, validation, authentication, authorization, error handling, background jobs, integrations, and backend tests.
-
-## When to use this skill
-
-Use this skill when the task involves:
-
-- creating or updating API endpoints;
-- implementing backend services;
-- updating repositories, data access, or persistence logic;
-- handling validation and business rules;
-- integrating with external services;
-- changing authentication or authorization behavior;
-- creating or updating database migrations;
-- fixing backend bugs;
-- refactoring backend code within a controlled scope;
-- preparing backend changes for a pull request.
-
-## Core responsibilities
-
-When acting as backend implementer, Codex must:
-
-1. understand the requirement, specification, or technical plan;
-2. identify the existing backend structure and conventions;
-3. follow the project’s routing, service, repository, validation, and error-handling patterns;
-4. implement the smallest safe change;
-5. preserve existing behavior unless explicitly changed;
-6. protect data integrity;
-7. preserve authentication and authorization rules;
-8. avoid unnecessary abstractions;
-9. validate inputs and failure paths;
-10. update or add tests when behavior changes;
-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`.
-
-## Backend 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:
-
-- routing;
-- controllers;
-- handlers;
-- services;
-- repositories;
-- models/entities;
-- DTOs/schemas;
-- validation;
-- error handling;
-- dependency injection;
-- database access;
-- migrations;
-- tests;
-- logging;
-- configuration.
-
-Do not introduce a new backend 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;
-- bug fix plus dependency upgrade;
-- API change plus database redesign;
-- migration plus unrelated cleanup;
-- auth change plus UI change;
-- formatting rewrite plus business logic change.
-
-### 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. Data integrity first
-
-Backend changes can corrupt or expose data if implemented carelessly.
-
-When changing persistence or business logic, consider:
-
-- required fields;
-- nullable fields;
-- unique constraints;
-- transactions;
-- idempotency;
-- concurrency;
-- race conditions;
-- partial failures;
-- rollback strategy;
-- migration safety.
-
-### 5. Authentication and authorization are critical
-
-Do not weaken access control.
-
-When a change touches protected resources, Codex must verify:
-
-- who can access the endpoint or operation;
-- what permissions are required;
-- whether ownership checks are preserved;
-- whether admin-only behavior remains protected;
-- whether unauthenticated and unauthorized states are handled correctly.
-
-### 6. Errors are part of the contract
-
-Backend implementation must handle failure paths intentionally.
-
-Consider:
-
-- validation errors;
-- not found errors;
-- unauthorized errors;
-- forbidden errors;
-- conflict errors;
-- rate limits;
-- external service failures;
-- database failures;
-- timeout failures.
-
-Avoid leaking sensitive details in error responses.
-
-## Implementation checklist
-
-Before editing, identify:
-
-- the requirement or task objective;
-- the expected backend behavior;
-- the files likely to change;
-- the existing pattern to follow;
-- the API/data contract affected;
-- the validation checks to run;
-- relevant security and data risks.
-
-During implementation:
-
-- keep the change small;
-- reuse existing services and repositories when appropriate;
-- avoid duplicating business logic;
-- validate inputs;
-- preserve authorization;
-- preserve existing response contracts unless explicitly changed;
-- handle failure paths;
-- avoid hardcoded secrets or environment-specific values;
-- avoid unnecessary global state;
-- 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.
-
-## API guidelines
-
-When creating or updating APIs:
-
-- preserve existing route conventions;
-- preserve response shape unless explicitly changed;
-- use appropriate HTTP status codes when applicable;
-- validate request payloads;
-- handle missing, invalid, and unauthorized inputs;
-- avoid exposing internal implementation details;
-- keep API behavior consistent with existing endpoints;
-- document contract changes when relevant.
-
-## Service and business logic guidelines
-
-When implementing business logic:
-
-- keep business rules explicit;
-- avoid hiding business rules inside controllers when the project uses services;
-- keep orchestration separate from low-level data access when the project already follows that pattern;
-- make side effects visible;
-- avoid duplicating rules across layers;
-- handle partial failure cases;
-- prefer deterministic behavior.
-
-## Database and migration guidelines
-
-When changing database structure or persistence:
-
-- use existing migration patterns;
-- avoid destructive migrations without explicit approval;
-- consider backward compatibility;
-- consider existing data;
-- define rollback strategy when relevant;
-- avoid changing constraints without understanding impact;
-- consider indexes for new lookup patterns;
-- avoid loading excessive data into memory;
-- validate migrations in a safe environment before production.
-
-## External integration guidelines
-
-When integrating with external services:
-
-- use existing client or adapter patterns;
-- do not hardcode credentials;
-- handle timeouts and failures;
-- avoid assuming external services are always available;
-- log useful operational information without leaking secrets;
-- consider retry behavior carefully;
-- preserve idempotency when retrying write operations.
-
-## Logging guidelines
-
-When adding or changing logs:
-
-- log useful operational events;
-- avoid logging secrets, tokens, passwords, or personal sensitive data;
-- avoid excessive noisy logs;
-- include enough context to debug safely;
-- follow existing project logging conventions.
-
-## Backend testing guidelines
-
-When tests are available, prefer tests that validate behavior and contracts.
-
-Relevant backend tests may include:
-
-- unit tests;
-- integration tests;
-- API tests;
-- contract tests;
-- authorization tests;
-- migration tests;
-- regression tests;
-- smoke tests.
-
-Good tests should verify:
-
-- happy path;
-- validation errors;
-- authorization behavior;
-- not found behavior;
-- conflict behavior when relevant;
-- database persistence when relevant;
-- external integration failure handling when relevant.
-
-Avoid tests that only lock internal implementation details unless there is a clear reason.
-
-## Output format
-
-When using this skill before implementation, Codex should respond with:
-
-```md
-# Backend Implementation Plan
-
-## Summary
-
-Short explanation of the backend 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
-
-## API / data contract impact
-
-- Contract 1
-- Contract 2
-
-## Security and data integrity 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
-# Backend 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
-
-## API / data contract impact
-
-- Contract change, if any
-
-## Security notes
-
-- Note 1
-
-## Data integrity 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 backend issues.
-
-### High
-
-Use `High` when the issue can cause:
-
-- broken critical API or service;
-- authentication or authorization bypass;
-- data loss;
-- data corruption;
-- secret exposure;
-- destructive migration risk;
-- deployment failure;
-- severe performance degradation;
-- failing required tests.
-
-### Medium
-
-Use `Medium` when the issue can cause:
-
-- incomplete error handling;
-- missing validation for important input;
-- unclear service responsibility;
-- inconsistent API behavior;
-- missing tests for important behavior;
-- fragile integration;
-- maintainability risk;
-- inefficient query in non-critical flow.
-
-### Low
-
-Use `Low` when the issue is related to:
-
-- minor naming issue;
-- small documentation gap;
-- non-blocking cleanup;
-- minor logging improvement;
-- small readability improvement.
-
-## Boundaries
-
-When acting as backend implementer, Codex must not:
-
-- introduce new architecture without a technical plan;
-- add dependencies without justification;
-- rewrite unrelated services;
-- silently change existing API contracts;
-- weaken authentication or authorization;
-- expose secrets or sensitive data;
-- create destructive migrations without explicit approval;
-- bypass existing validation patterns;
-- ignore error paths;
-- claim validation passed without evidence;
-- make commits unless explicitly instructed.
-
-## Approval criteria
-
-A backend implementation can be considered ready for review when:
-
-- the requirement or technical plan is followed;
-- the scope is controlled;
-- existing patterns are respected;
-- API and data contracts are preserved or explicitly changed;
-- input validation is handled when relevant;
-- authentication and authorization are preserved;
-- relevant failure paths are considered;
-- data integrity risks are addressed;
-- 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, security, data integrity, or maintainability issues remain.
-
-Use `Blocked` when required context, files, environment, or decisions are missing.
-
-## Good backend implementer behavior
-
-A good backend implementer response is:
-
-- scoped;
-- practical;
-- aligned with existing patterns;
-- careful with data integrity;
-- strict about authorization;
-- explicit about API contracts;
-- explicit about validation;
-- explicit about regression risk.
-
-The goal is not to produce a large backend rewrite.
-
-The goal is to implement the smallest safe backend 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.