Mavixx Forge

View saved version →

---
name: mavixx-design-system
description: Define and apply a project-specific visual system to a real user interface using approved brand assets, existing product patterns, or an inferred design direction. Use for new UI implementation, substantial UI or UX upgrades, broad redesigns, or inconsistent interfaces; use `$mavixx-project-upgrade` as the orchestrator for a full existing-project upgrade and do not activate for backend-only work.
---

# Mavixx Design System

Create and implement a distinctive, usable visual direction without forcing one aesthetic on every product. Documentation supports the interface; it does not replace the interface.

Read [references/design-workflow.md](references/design-workflow.md). Adapt [assets/DESIGN.template.md](assets/DESIGN.template.md) into the project's root `DESIGN.md` when a durable design source of truth is useful. If the user asked to build or improve the UI, continue by applying the system to the actual source code.

## Inputs and decisions

Inspect existing brand assets and UI first. Classify missing inputs:

- **Blocking:** brand identity conflict, regulated content, required licensed font/assets, or a visual direction with materially different implementation cost.
- **Recommended:** logo, audience, personality, competitor/reference examples, preferred and forbidden styles.
- **Generatable:** initial palette, type pairing, tokens, component language, motion direction, and placeholder imagery.

When references are absent, derive a recommended direction from the product, audience, task frequency, content density, and existing brand. Present multiple directions only when the choice materially changes identity or implementation cost, or when the user requests options. When references are provided, extract principles—hierarchy, rhythm, density, composition, and motion—without copying protected brand elements or content.

## Rules

- When created, `DESIGN.md` must define semantic tokens, typography, spacing, layout, components, states, imagery, motion, responsive behavior, accessibility constraints, and an explicit anti-pattern list.
- Preserve an existing working design unless redesign is requested or inconsistency is part of the task.
- Prefer coherent native components over a collage of unrelated component-library examples.
- Implement foundations in the project's existing styling system, then update shared components and page shells before one-off page decoration.
- Preserve functioning routes, content, data states, forms, and interactions. A visually polished static mock is not a successful upgrade of a working product.
- Treat third-party design skills such as `gpt-taste` as optional specialists. Recommend them only when their strong editorial/GSAP style fits; disclose the source and obtain approval before installation.
- Start or preview the app, inspect representative desktop and mobile states, correct visual and interaction defects, and invoke `$mavixx-quality-gates` after implementation. Do not claim the UI was upgraded from source inspection alone.

Referenced files: 3

View saved version →

---
name: mavixx-forge
description: Orchestrate Mavixx Forge across a new or existing software project and carry the requested work through implementation and verification. Use when the user explicitly says Mavixx Forge, asks to set up or build a new project, or wants an existing website or app upgraded, redesigned, stabilized, or finished. Do not use for a generic coding question with no project work.
---

# Mavixx Forge

Turn the user's request into a working, verified project result. An audit, plan, `PROJECT_BRIEF.md`, or `DESIGN.md` may support the work, but none is a substitute for implementation when the user asked to build, fix, set up, modernize, redesign, or upgrade.

Read [references/operating-modes.md](references/operating-modes.md), inspect the active workspace, and select one route. On a compatible shell, `../../scripts/preflight_inventory.sh <project-root>` can provide an initial inventory; supplement it with direct inspection and never treat its output as verification.

- **New or starter-only project:** use `$mavixx-project-bootstrap`, then continue into implementation when the user requested a build.
- **Existing website or application:** use `$mavixx-project-upgrade`. For material interface work, also use `$mavixx-design-system` and follow its implementation loop.
- **Verification or release review:** use `$mavixx-quality-gates`.
- **Narrow known fix:** handle it directly with project-native conventions; do not inflate it into a broad redesign unless requested.

## Execution contract

- Treat an explicit request to build, set up, fix, upgrade, redesign, modernize, or finish as authorization to edit files within that scope. Do not ask for approval again merely because implementation is substantial.
- Ask only when a missing choice materially changes business behavior, architecture, data safety, cost, brand identity, or the requested outcome and cannot be inferred safely.
- If editable source is absent, explain that a URL alone permits inspection but not implementation, and ask the user to open or attach the repository. Do not claim the website was upgraded.
- Read repository instructions and Git status before editing. Preserve unrelated user changes, working behavior, data, public routes, integrations, analytics, and brand assets unless the request changes them.
- Prefer the existing stack and conventions. Do not replace a framework or introduce a new design library solely to make the result look different.
- Keep moving through safe, in-scope work while a non-blocking detail is unresolved. Record reasonable defaults instead of turning every preference into a question.
- Use rendered evidence for interface claims. Start the app when possible, inspect representative desktop and mobile states, exercise important interactions, fix observed issues, and rerun affected checks.

## Completion contract

Do not finish an implementation request with only recommendations. Finish when the requested code or configuration is changed, relevant checks have been run, critical flows are exercised, and UI work has been inspected in a rendered state. Report implemented changes, evidence, pre-existing failures, remaining blockers, and any deployment action that still requires separate authority.

Referenced files: 2

View saved version →

---
name: mavixx-project-bootstrap
description: Prepare and begin implementing a new software project by resolving material requirements, establishing useful project guidance, and choosing an architecture and design direction. Use for a new build, an untouched starter, or a formally requested rebuild; route a functional or partially built existing codebase to `$mavixx-project-upgrade` and do not use for a narrow known fix.
---

# Mavixx Project Bootstrap

Complete a proportional preflight before material implementation. Preflight is a delivery phase, not the final result when the user asked to set up or build the project.

## Route the project

- Empty or starter-only folder: use **new mode**.
- Functional or partially implemented codebase: do not apply a new-project setup over it; use **existing mode** and route the work to `$mavixx-project-upgrade`.
- Unclear state: inspect files, Git status, manifests, routes, and build commands before deciding.

Read [references/preflight.md](references/preflight.md) and follow only the selected mode. Use [assets/AGENTS.template.md](assets/AGENTS.template.md) and [assets/PROJECT_BRIEF.template.md](assets/PROJECT_BRIEF.template.md) as adaptable output templates.

## Preflight contract

1. Classify known inputs as **confirmed**, **safely inferable**, **optional**, or **blocking**.
2. Ask only about blocking decisions whose answers materially change architecture, data handling, cost, brand direction, or user experience.
3. Offer a recommended choice whenever practical. Never invent credentials, legal claims, customer proof, brand assets, or business rules.
4. For a new project, create or update `PROJECT_BRIEF.md`, root `AGENTS.md`, and an implementation plan when they improve continuity. For an existing repository, preserve and extend current instructions instead of replacing them with generic templates. Invoke `$mavixx-design-system` when the product has a user interface.
5. Present a concise preflight summary: project mode, confirmed decisions, missing items, proposed defaults, risks, phases, and definition of done.
6. If the user already requested the build or setup, continue into implementation after actual blockers are resolved. Pause only for unresolved choices that materially change the product, architecture, data safety, cost, or brand identity; do not pause merely because the requested work is substantial.

## External resources

Do not silently install third-party skills or copy design systems. If an external skill, reference website, font, component, API, or asset library would materially improve the project, explain what it contributes, its source/license when known, and whether it is required or optional. Obtain approval before installation or external mutation.

## Completion

Preflight is complete when another Codex thread can understand the product, constraints, commands, architecture direction, and acceptance criteria from project files without relying on chat history. The user's build request is complete only after the implementation and relevant verification are also complete.

Referenced files: 4

View saved version →

---
name: mavixx-project-upgrade
description: Implement and verify an end-to-end upgrade of an existing website or software project while preserving working behavior, user changes, data, routes, integrations, and brand intent. Use for broad modernization, UI or UX improvement, redesign, stabilization, inherited projects, or completing a partially built codebase; do not use for an audit-only request or a narrow known fix unless explicitly invoked.
---

# Mavixx Project Upgrade

Use an audit-first, checkpointed upgrade that continues into implementation. Never treat modernization as permission to rewrite the project, and never treat the audit as completion when the user requested an upgrade.

Read [references/upgrade-protocol.md](references/upgrade-protocol.md) before changing code. For any user-facing website or interface upgrade, also read [references/ui-upgrade.md](references/ui-upgrade.md).

## Authorization and mode

- If the user asks only to audit, review, explain, or plan, inspect and report without changing files.
- If the user asks to upgrade, modernize, redesign, improve, set up, finish, or fix the existing project, that request authorizes implementation within the stated scope. Do not stop for a redundant approval after presenting the audit or plan.
- If the editable repository is not present in the active workspace, stop and request the source. A live URL is not an editable project.

## Required behavior

1. Locate the real project root. Read applicable repository instructions, Git status/history, manifests, architecture, routes, data models, environment-variable names, tests, and deployment configuration.
2. Establish a baseline with safe project-native checks. For UI work, run the application and inspect representative pages at desktop and mobile widths before editing. Record pre-existing failures separately.
3. Map critical user journeys and invariants. Identify what must remain stable, what is broken, what is incomplete, and what is merely dated.
4. Create a concise prioritized working audit covering only relevant functionality, setup, UX, visual consistency, responsiveness, accessibility, performance, security, maintainability, dependencies, and release risk. Separate **must fix**, **recommended**, and **optional redesign** work.
5. Make a recoverable Git checkpoint when safe and useful. Never overwrite unrelated dirty changes or user-owned files.
6. Implement the authorized scope in reviewable phases. Prefer shared foundations before page-by-page patches. Keep data, APIs, URLs, analytics, SEO, authentication, and deployment compatibility stable unless the request changes them.
7. For visual changes, use `$mavixx-design-system` to establish direction and apply it to the code. A `DESIGN.md` file alone is not an upgraded UI.
8. After each material phase, use `$mavixx-quality-gates`, fix in-scope failures, and repeat affected checks. Visually inspect the rendered UI rather than inferring quality from source code.

Stop and request direction only when the upgrade requires destructive data changes, unavailable required credentials, an uncertain business rule that changes behavior, a brand conflict that approved assets cannot resolve, missing editable source, or a materially expanded scope. Continue all safe work that is not blocked.

## Completion gate

Do not hand off an upgrade while safe in-scope implementation remains. Completion requires actual source or configuration changes, relevant build and test evidence, exercised critical journeys, and rendered desktop/mobile evidence for UI work. Clearly distinguish remaining blockers and pre-existing failures from the completed upgrade.

Referenced files: 3

View saved version →

---
name: mavixx-quality-gates
description: Verify a software project or material project phase with evidence-based functional, visual, accessibility, performance, security, and release checks. Use before handoff or deployment and after broad upgrades; scale checks down for small changes.
---

# Mavixx Quality Gates

Test the changed behavior and the risks introduced by the task. Read [references/quality-matrix.md](references/quality-matrix.md) and select applicable gates rather than running irrelevant tooling. When invoked during an authorized implementation, fix in-scope failures and rerun the affected gates instead of only listing defects.

## Verification order

1. Preserve the baseline: distinguish new failures from pre-existing failures.
2. Run repository-defined format, lint, type, unit, integration, and build checks.
3. Exercise critical user journeys and negative/error states.
4. For interfaces, start the app and inspect rendered desktop and mobile states, interactions, overflow, loading, empty, success, and error states. Compare against the pre-change baseline when available and capture evidence when tools allow it. Source inspection alone cannot pass the visual gate.
5. Check keyboard use, focus visibility, semantic structure, labels, contrast, and reduced-motion behavior where applicable.
6. Assess exposed secrets, authorization boundaries, input validation, unsafe data handling, and dependency risk proportionate to the change.
7. Evaluate performance where the change affects load, rendering, media, animation, queries, or bundles.
8. Fix issues within scope and repeat affected checks until they pass or a concrete blocker remains.

## Exit report

Report commands/checks run, results, visual states inspected, fixes made, remaining risks, skipped gates with reasons, and deployment or rollback notes. Never claim a gate passed without observable evidence. A project is not release-ready while a critical journey fails, the build is broken, a high-impact security issue remains, required user input is unresolved, or a claimed UI upgrade has not been rendered and inspected.

Referenced files: 2