Russian version

Codex Workflow Skills

A portable workflow layer for using Codex on real software projects.

This repository is not an application framework. It provides:

• AGENTS.md — repository execution rules for Codex.
• .agents/skills/ — reusable workflow skills for planning, implementation, frontend/design, validation, CI/CD, smoke/e2e testing, and platform work.
• Use Cases.md — copy-paste commands for invoking the skills effectively.
• scripts/validate.sh — local validation for skill metadata, bundled scripts, documentation symmetry, and repository hygiene.

Why use it

Use this package when you want Codex to work with repeatable execution standards instead of ad-hoc prompts:

• build or repair project context before coding;
• turn vague tasks into executable task contracts;
• implement with bounded scope and repository evidence;
• transform public/internal frontend surfaces with UI/UX skills;
• choose and apply site design references as root DESIGN.md;
• validate patches, builds, migrations, transactions, locks, and release readiness;
• generate GitHub Actions CI/CD with protected-branch merge gates, test blocking, merge conflict/up-to-date policy, first-time server deploy, deploy concurrency, health checks, and rollback/no-switch behavior;
• generate or update critical smoke/e2e tests that lock changed behavior and can become PR/deploy gates;
• add practical platform workflows such as minimal CI, Nginx, Prometheus/Grafana, worker queues, OpenAI SDK setup, and external API integrations.

Repository layout

AGENTS.md
README.md
README.ru.md
Use Cases.md
Use Cases.ru.md
CONTRIBUTING.md
CHANGELOG.md
LICENSE
.github/
  workflows/
    validate.yml
scripts/
  validate.sh
.agents/
  skills/
    project-context/
    task-synthesis/
    implementation-workflow/
    frontend-product-design/
    site-references/
    ui-ux-pro-max/
    product-marketing-copy/
    validation-hardening/
    github-actions-cicd/
    e2e-smoke-tests/
    platform-ops/

Install into a project

Copy the workflow files into the root of the target repository:

cp -R AGENTS.md "Use Cases.md" "Use Cases.ru.md" .agents /path/to/your-project/

If the target project already has AGENTS.md, merge the rules instead of overwriting them.

Do not copy this repository README.md over a target project README. A target project README should describe that specific product and architecture. Use the project-context skill to create or repair it.

Start using it

Open Use Cases.md and copy the command that matches the task.

Examples:

Use skill `project-context` to complete the task: create or update README.md as the project context document. Do not change code.

Use skill `task-synthesis` to complete the task: create task_contract.md for <task>. Do not change code yet.

Use skills `frontend-product-design` and `ui-ux-pro-max` to complete the task: bring the public frontend to production-quality level without changing backend/domain logic.

Use skill `github-actions-cicd` to complete the task: generate production-ready GitHub Actions CI/CD with PR checks, required status checks, merge conflict/up-to-date gate, auto-deploy only after a successful merge to main, first-time server deploy, health check, and rollback/no-switch behavior.

Skills

Skill	Use it for
project-context	README generation, repository map, project context repair, and workflow routing.
task-synthesis	Task contracts, clarification, high-impact issue discovery, and evolution plans.
implementation-workflow	Executing approved task contracts and safe behavior-preserving refactoring.
frontend-product-design	Frontend audit, design contracts, visual assets, page/public/dashboard/internal UI transformation, and visual QA.
site-references	Local website reference selection and application as root DESIGN.md; use for reference-driven frontend direction.
ui-ux-pro-max	Executable UI/UX and visual design workflows with data, scripts, references, and optional asset generation/sourcing.
product-marketing-copy	Product positioning, landing/pricing/auth/onboarding copy, CTA clarity, and microcopy without unsupported claims.
validation-hardening	Patch checking, build/test gate, transaction/lock/idempotency review, and database migration safety.
github-actions-cicd	GitHub Actions CI/CD, protected-branch merge gates, failed-test deploy blocking, merge conflict/up-to-date policy, first-time server deploy, environment secrets, deploy concurrency, health checks, and rollback/no-switch behavior.
e2e-smoke-tests	Critical smoke/e2e test generation, changed-behavior regression locking, Playwright/browser scenarios, stable selectors, fixtures, and CI smoke gates.
platform-ops	Minimal CI baseline, release readiness, dependencies, security, API integrations, Nginx, OpenAI SDK, Prometheus/Grafana, and worker queues.

Required skill routing

AGENTS.md contains the authoritative routing rules. The practical rule is: use the relevant skill before work that needs its contract, then use validation-hardening after any non-trivial patch.

Situation	Required skill path
Missing/stale README or broad workflow selection	Start with project-context.
Ambiguous or risky implementation request	Start with task-synthesis, then move to implementation-workflow.
Approved code/config/schema/runtime change	Use implementation-workflow for execution and validation-hardening after edits.
Critical user/business behavior changed	Add/update focused coverage with e2e-smoke-tests, then run validation-hardening.
CI/CD, GitHub Actions, required checks, merge conflicts, merge queue, auto-deploy, or first server deploy	Use github-actions-cicd; use validation-hardening after workflow/script edits.
Frontend/UI/visual change	Use frontend-product-design and ui-ux-pro-max; use validation-hardening after implementation.
Site-reference-driven frontend direction	Use site-references first, then frontend-product-design and ui-ux-pro-max.
Platform work that is not production GitHub auto-deploy	Use platform-ops; route production GitHub deploy gates to github-actions-cicd.
Product-facing copy	Use product-marketing-copy.

GitHub Actions CI/CD and e2e workflow

Use github-actions-cicd when you need production-grade GitHub Actions instead of a minimal CI baseline. The skill separates PR validation, merge permission, and deployment: tests run on PRs, branch protection/rulesets require passing checks and conflict-free/up-to-date branches, and auto-deploy runs only after the protected branch receives a valid merge.

Use skill `github-actions-cicd` to complete the task: generate production-ready GitHub Actions CI/CD for this project: PR checks, required status checks, merge conflict/up-to-date gate, auto-deploy only after successful merge to main, first-time server deploy, health check, and rollback/no-switch.

Use e2e-smoke-tests when a change must be locked with critical smoke/e2e coverage.

Use skill `e2e-smoke-tests` to complete the task: from the current diff, identify critical user scenarios and add/update smoke/e2e tests that lock the changed logic.

Use both skills when tests must become a merge or deploy gate.

Use skills `e2e-smoke-tests` and `github-actions-cicd` to complete the task: add/update smoke/e2e tests for the changed behavior and wire the smoke/e2e job into required GitHub checks and deploy dependencies.

Site references workflow

Use site-references when you want Codex to choose a visual reference before frontend work. The skill can shortlist references, apply one as root DESIGN.md, and then hand off implementation to frontend-product-design + ui-ux-pro-max.

Use skill `site-references` to complete the task: select 3-5 site references for the project frontend direction, recommend the best option, and explain the choice. Do not change code.

Use skills `site-references`, `frontend-product-design`, and `ui-ux-pro-max` to complete the task: apply reference <slug> and bring the public frontend to that visual direction without copying brand identity, logos, exact content, or fake claims.

Optional runtime keys

Some ui-ux-pro-max asset workflows can use external services. Never commit keys or .env files.

Use environment variables only:

OPENAI_API_KEY
PEXELS_API_KEY

If keys or network access are unavailable, the skills must produce deterministic specs, prompts, SVG/code, search queries, CSS treatments, or implementation guidance instead of faking generation.

Validate the package

Run:

bash scripts/validate.sh

The validator checks:

• each skill has SKILL.md;
• each skill frontmatter has only name and description;
• folder names match skill names;
• AGENTS.md contains the mandatory skill-routing section and references all bundled skills;
• workflow-router.md routes all bundled skills;
• README and Use Cases documents mention existing skills and keep mirrored EN/RU heading structure;
• local Markdown links and skill reference links resolve;
• English README, Use Cases, and skill docs contain no Cyrillic text;
• Python scripts compile;
• .cjs scripts pass node --check when Node is available;
• common junk, secrets, caches, old prompt folders, and generated artifacts are absent.

The GitHub Actions workflow runs the same validation on pushes and pull requests.

Contributing

See CONTRIBUTING.md.

Keep changes practical: improve execution quality, reduce ambiguity, or add a broadly reusable workflow skill. Avoid decorative docs, duplicate rules, or one-off project assumptions.

License

MIT. See LICENSE.