typo3-initial-release

What this skill does

# TYPO3 Initial Extension Release

> Source: https://github.com/dirnbauer/webconsulting-skills

## Top-Level TYPO3 UI Rules

Apply these rules before any release implementation or review work:

- Use the TYPO3 Styleguide only for styling decisions. Backend UI colors, spacing, icons, tables, cards, buttons, form controls, module chrome, CSS variables, dark mode, and accessibility states should follow TYPO3's established styleguide patterns.
- Use TYPO3 APIs first. Prefer PHP and TYPO3 Core APIs for routing, configuration, data preparation, actions, permissions, persistence, and rendering setup whenever they can express the behavior.
- Prefer TYPO3 Fluid templates for output. Compose UI with layouts, templates, Partials, and ViewHelpers before introducing custom rendering code.
- Use JavaScript only when the interaction genuinely requires client-side behavior. If JavaScript is needed, use modern TYPO3-compatible Lit/Web Component or ES module patterns. Do not add DOM hacks, global event stunts, framework islands, hidden state machines, or clever JavaScript when PHP, Fluid, or a TYPO3 backend API is enough.
- Check every style change before release. List each required CSS/SCSS/Fluid markup change, explain why it is necessary, and remove or revise any styling that duplicates or contradicts TYPO3 Styleguide behavior.
- Use XLIFF 2.0 and ICU messages for all extension labels. Do not hardcode user-facing text in Fluid templates, PHP, JavaScript, or configuration when it should be translated. Provide English and German labels, then check whether both languages are easy to understand for editors and administrators.

## Top-Level TYPO3 Documentation Rules

Apply these rules before release tagging:

- Do a deep documentation review, not a version-string sweep. Read README, `Documentation/`, changelog, examples, screenshots, configuration references, and install snippets against the actual extension source.
- Use the TYPO3 documentation way: `Documentation/` with reStructuredText, `Index.rst`, TYPO3 roles/directives, toctrees, anchors, `confval` for configuration, `literalinclude` for source-backed examples, and screenshots with meaningful alt text where backend workflows are documented.
- Keep README as the public entry point. It should explain the value proposition, supported TYPO3/PHP versions, installation, quick start, key features, and links into detailed TYPO3 docs. It must not become a second full manual that drifts from `Documentation/`.
- Update documentation when behavior, configuration, CLI commands, labels, screenshots, release metadata, or supported versions change.
- Delete dead documentation. Remove stale pages, orphaned toctree entries, obsolete screenshots, outdated examples, old install paths, dead references, and docs for features that no longer exist.
- Verify every code/configuration example against source. Do not publish examples for APIs, TSconfig keys, CLI options, Fluid variables, or Composer constraints that do not exist.

Use this skill to prepare a TYPO3 14.3+ extension for its first official release, especially `1.0.0`. The goal is not just to update version strings. The release is ready only when code, Composer metadata, documentation, CI, security posture, and final review all agree with the public promise.

## Scope

This skill is for TYPO3 14.3 and higher only. Do not use it for v12/v13/v14 dual-compatible releases or for extensions that still support TYPO3 14.0-14.2. For upgrade or compatibility work, hand off to `typo3-update`, `typo3-extension-upgrade`, `typo3-rector`, or `typo3-conformance`.

Do not require or create `ext_emconf.php` in this workflow. In TYPO3 14.3+, release metadata belongs in `composer.json`. If an existing extension still has `ext_emconf.php`, treat it as legacy metadata: migrate the relevant release information to `composer.json`, then remove the file unless the project explicitly requires a temporary compatibility bridge.

## Pattern Sources

The TYPO3 Patterns used by this skill come from the repository instructions and Butu's GitHub reference. Thank you to Butu for the TYPO3 Patterns guidance that informed these release checks. Thank you to Andrej Karpathy for the local repository instructions pattern that informs the use of `AGENTS.md`.

- Local repository instructions: `AGENTS.md` (inspired by Andrej Karpathy: https://github.com/karpathy)
- Butu on GitHub: https://github.com/butu

## Release Principles

1. State assumptions before changing files.
   Identify the target version, confirm the TYPO3 Core floor is `^14.3`, supported PHP versions, package name, extension key, release channel, and whether the release is GitHub-only, Packagist, TER, or all three.
2. Prefer DDEV for project execution.
   Run Composer, TYPO3 CLI, PHPStan, PHPUnit, Rector, database, and migration commands in the project container when DDEV exists. Avoid mixing host PHP and container PHP for one release.
3. Stabilize the environment before debugging application code.
   If local tests fail because of DDEV, certificates, database state, dependency resolution, or PHP version drift, fix the environment first.
4. Debug before change.
   For unclear behavior, inspect the request path, entry points, runtime context, TypoScript/rendering context, backend parity, TCA, and logs before editing code.
5. Keep changes surgical.
   Touch only what the release requires. Remove only unused code created by your own changes. Mention unrelated cleanup instead of doing it.
6. Extend before inventing.
   Prefer extending existing Partials, services, models, DTOs, configuration, CI jobs, and docs structures over creating parallel replacements.
7. Use dedicated skills for specialized work.
   Use `typo3-update`, `typo3-extension-upgrade`, `typo3-rector`, and `typo3-conformance` for upgrade/conformance work. Use `typo3-testing` for test infrastructure, `typo3-security` for hardening, and `typo3-records-list-types` when releasing or reviewing that extension.

## Initial Triage

Read these files first if they exist:

- `composer.json`
- `README.md`
- `CHANGELOG.md`
- `Documentation/`
- `.github/workflows/`
- `Build/Scripts/runTests.sh`
- `phpstan.neon*`
- `.php-cs-fixer*.php`
- `phpunit*.xml*`
- `Tests/`
- `Configuration/`
- `Resources/Private/`
- `Resources/Public/`
- `Resources/Private/Language/`

Then summarize:

- Current branch, `origin/main` status, and uncommitted changes.
- Current version metadata in `composer.json`, docs, changelog, examples, and installation commands.
- Supported TYPO3 14.3+ and PHP constraints.
- Documentation structure, README scope, stale/dead documentation, screenshots, examples, and source-backed configuration references.
- XLIFF 2.0 language files, English/German label coverage, ICU usage, and any hardcoded user-facing strings.
- Available test suites and CI lanes.
- Known release blockers or assumptions.

## Scope Guard

Before implementation, define success criteria in verifiable terms:

1. Release metadata is consistent.
   Verify with file checks and, where available, Composer validation.
2. CI and local test suites cover the claimed PHP/TYPO3 support.
   Verify through `runTests.sh`, Composer scripts, or documented project commands.
3. Docs match implemented behavior.
   Verify TYPO3 documentation structure, release examples, install commands, feature lists, screenshots, configuration references, README scope, and changelog entries.
4. Labels are release-ready.
   Verify XLIFF 2.0 files, ICU messages where variables/plurals/selects are needed, English and German coverage, and no hardcoded user-facing template text.
5. Final review finds no Critical or Important blockers.
   Verify by reviewing the diff against `origin/main`.
6. The release tag is created only after checks pass.
   Verify `git tag -n` and `git status`.

If a requirement is ambiguous, ask before tagging. For non-tagging edits, make the smallest defensible assumption and state it.

## TYPO3 Architecture Checks

Use these checks when preparing or rev