netresearch/typo3-docs-skill / skills/typo3-docs
typo3-docs
FlaggedUse when TYPO3 extension documentation has to render on docs.typo3.org, which builds a manual from Documentation/guides.xml and reads no Settings.cfg (a single README.rst serves an extension too small for one): when an extension has no documentation yet, or when creating, editing or reviewing Documentation/*.rst, guides.xml, README.md or XLF translations, rendering docs with Docker, TYPO3 RST directives, screenshots, or XLIFF 2-space indentation (TYPO3 v14+).
checkpoints.yaml
View on GitHub# SPDX-License-Identifier: MIT
# SPDX-FileCopyrightText: Netresearch DTT GmbH
#
# Checkpoints for typo3-docs skill
# Validates TYPO3 extension documentation following docs.typo3.org standards
#
# THREE TRAPS THIS FILE HAS BEEN BITTEN BY — read before adding a checkpoint.
#
# 1. `cmd | head -1 && echo … && exit 1 || exit 0` can never pass: `head` exits 0
# on EMPTY input, so the `&&` branch fires whatever the tree contains. The
# runner also rejects `&&`/`||`/`;` outright, so the checkpoint never ran and
# the reported failure was the rejection, not a finding. Derive the exit
# status from the match itself — `! grep -rq …`.
#
# 2. A `find`/`grep -r` with no exclusion for .Build/, vendor/ and node_modules/
# matches inside ignored dependency trees. Every recursive scan here carries
# `-not -path '*/vendor/*'` (find) or `--exclude-dir=vendor` (grep). The
# spelling is `*/vendor/*`, not `./vendor/*`: under `find Documentation/`
# paths print as `Documentation/…` with no `./` prefix, so a `./`-anchored
# exclusion would never match anything.
#
# 3. A checkpoint runs from the root of the repository UNDER ASSESSMENT, where
# this skill's own scripts/ directory does not exist — and the runner rejects
# any base command carrying a path prefix anyway. `bash scripts/check-foo.sh`
# is therefore always a dead checkpoint. Logic that needs loops, `$( )` or
# `;` is inlined below as `type: script` with a `command: |` block, which the
# runner writes to a temp file and executes with bash (checkpoints-schema.md,
# "type: script"). The shipped scripts/*.sh stay as the human-facing entry
# point and are the reference these bodies mirror.
#
# On `type: script` bodies: they carry no `set -euo pipefail`. Every one of them
# ends in an explicit `exit`, and under `set -e` a `grep … | head -1 | grep …`
# capture fails on SIGPIPE — which would be trap 1 again in a different costume.
version: 1
skill_id: typo3-docs
# Only run for TYPO3 extensions (SKILL.md compatibility: "A TYPO3 extension;
# Documentation/ may be absent"), so a missing Documentation/ is still reported
# there. Without this gate /assess ran every check against a Python repository.
preconditions:
- type: json_path
target: composer.json
pattern: '.type == "typo3-cms-extension"'
mechanical:
# === DIRECTORY STRUCTURE ===
- id: TD-01
type: file_exists
target: Documentation/
severity: error
desc: "Documentation/ directory must exist"
- id: TD-02
type: file_exists
target: Documentation/Index.rst
severity: error
desc: "Documentation/Index.rst must exist as main entry point"
- id: TD-03
type: file_exists
target: Documentation/guides.xml
severity: error
desc: "Documentation/guides.xml must exist for rendering configuration"
# === EDITORCONFIG ===
- id: TD-04
type: file_exists
target: Documentation/.editorconfig
severity: warning
desc: "Documentation/.editorconfig should exist for consistent formatting (NR policy; upstream ships a sample)"
provenance: org-policy
source: https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Advanced/CodingGuidelines.html
verified: 2026-08-14
# === GUIDES.XML CONTENT ===
# Was `contains "<project"`, which a hallucinated
# `<project>my-extension</project>` satisfies — the renderer reads title and
# release from ATTRIBUTES, and an element carrying the extension key as text
# is the shape agents reach for. Measured against ten guides.xml files
# recorded from evaluated agent runs against a real extension: nine will not
# render, and the old pattern passed three of those nine. See issue #91.
#
# The namespace is phpDocumentor's, not TYPO3's: rendering is done by
# phpDocumentor Guides. Verified against georgringer/news,
# FriendsOfTYPO3/extension_builder, TYPO3CMS-Reference-TCA and
# helhum/typo3-console, which all declare exactly this one.
#
# Written as a self-contained command rather than a call to
# scripts/check-guides-xml-schema.sh, because a checkpoint runs from the
# repository root and the skill's own scripts are not there.
#
# It was spelled `pattern: >-` (a FOLDED block scalar) and therefore never
# executed once: run-checkpoints.sh recognises only the LITERAL `|` block
# header, so `>-` fell through to the plain-scalar branch and the whole
# command reached the allowlist as the two characters `>-`
# ("'>-' not in allowed command whitelist"). validate-checkpoints.sh accepts
# `>-` as a multi-line shape, so authoring-time validation did not catch it.
# Spell a multi-line body `type: script` + `command: |`, nothing else.
- id: TD-05
type: script
command: |
php -r '$d = new DOMDocument();
if (!@$d->load("Documentation/guides.xml")) { exit(1); }
$n = "https://www.phpdoc.org/guides";
if ($d->documentElement->namespaceURI !== $n) { exit(1); }
$p = $d->getElementsByTagNameNS($n, "project")->item(0);
if ($p === null) { exit(1); }
exit(trim($p->getAttribute("title")) !== "" && trim($p->getAttribute("release")) !== "" ? 0 : 1);'
severity: error
desc: "guides.xml must be in the phpDocumentor namespace with <project title=… release=…> as attributes"
- id: TD-06
type: contains
target: Documentation/guides.xml
pattern: "version="
severity: warning
desc: "guides.xml should specify documentation version"
# guides.xml extension identification — any of these per-line tokens
# satisfies the check. The previous regex required `<extension` and
# `class=` on the same line (rare in real guides.xml — TYPO3 docs
# convention puts each attribute on its own line). It also rejected
# the slash form `vendor/key` for interlink-shortcode (the real
# canonical form).
- id: TD-07
type: regex
target: Documentation/guides.xml
pattern: 'extension-key="[a-z_-]+"|<extension(>|[[:space:]]|$)|interlink-shortcode="[a-z_/-]+"'
severity: warning
desc: "guides.xml should identify the extension via extension-key=, <extension …>, or interlink-shortcode=vendor/key"
# === INDEX.RST CONTENT ===
- id: TD-08
type: regex
target: Documentation/Index.rst
pattern: "^={3,}$"
severity: error
desc: "Index.rst must have proper RST title underline"
- id: TD-09
type: contains
target: Documentation/Index.rst
pattern: ".. toctree::"
severity: warning
desc: "Index.rst should have toctree directive"
# === FILE NAMING (CamelCase) ===
# Carried both trap 1 and trap 2: `… | head -1 && exit 1 || exit 0` reported a
# finding on every tree, and the unfiltered find reached vendored .rst files.
# The status now comes from the match — the final `grep -qv` succeeds only if
# some lowercase-named path is not an Index.rst, and `!` turns that into a
# failure.
- id: TD-10
type: command
pattern: "! find Documentation/ -name '*.rst' -not -path '*/.Build/*' -not -path '*/vendor/*' -not -path '*/node_modules/*' | grep -E '/[a-z]' | grep -qv Index.rst"
severity: warning
desc: "RST files should use CamelCase naming (e.g., Configuration.rst not configuration.rst)"
# === IMAGE FORMAT ===
- id: TD-11
type: command
pattern: "! find Documentation/ -type f -not -path '*/.Build/*' -not -path '*/vendor/*' -not -path '*/node_modules/*' \\( -name '*.jpg' -o -name '*.jpeg' -o -name '*.gif' -o -name '*.bmp' \\) -print -quit | grep -q ."
severity: warning
desc: "Images should be PNG (or AVIF), not JPG/GIF/BMP — upstream allows PNG or AVIF"
provenance: upstream
source: https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Advanced/GuidelinesForImages.html
verified: 2026-08-14
- id: TD-12
type: file_exists
target: Documentation/Images/
severity: info
desc: "Documentation/Images/ directory should exist for screenshots"
# === README CONSISTENCY ===
- id: TD-13
type: file_exists
target: README.md
severity: warning
desc: "README.md should exist at repository root"
- id: TD-14
type: contains
target: README.md
pattern: "Documentation"
severity: info
desc: "README.md should reference the Documentation folder"
# === NO MAILTO LINKS ===
- id: TD-18
type: command
pattern: "! grep -rq --exclude-dir=.Build --exclude-dir=vendor --exclude-dir=node_modules -- 'mailto:' Documentation/"
severity: warning
desc: "No mailto: links; use GitHub Issues/Discussions URLs (NR policy — upstream explicitly allows mailto for project-contact)"
provenance: org-policy
source: "Netresearch: no email addresses in public docs (spam/PII); upstream allows them — https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Reference/GuidesXml.html"
verified: 2026-08-14
# === INDEX.RST IN SUBDIRECTORIES ===
# `xargs -I{}` runs one `test -f` per candidate and exits 123 as soon as one
# of them fails, which is the loop the runner's ban on `;` forbids writing by
# hand. Empty input exits 0 via `-r`.
#
# This is the one scan here that enumerates DIRECTORIES, so `-not -path
# '*/vendor/*'` would not be enough: it excludes what is inside vendor/ and
# not vendor/ itself, which would then be reported as a subdirectory missing
# its Index.rst. `-prune` excludes the directory and its contents both.
- id: TD-19
type: command
pattern: "find Documentation/ -mindepth 1 \\( -name .Build -o -name vendor -o -name node_modules \\) -prune -o -type d ! -name Images ! -name '_*' -printf '%p/Index.rst\\0' | xargs -0 -r -I{} test -f {}"
severity: warning
desc: "Every Documentation/ subdirectory must contain an Index.rst file"
# === GUIDES.XML THEME ===
- id: TD-25
type: contains
target: Documentation/guides.xml
pattern: 'theme="typo3docs"'
severity: warning
desc: "guides.xml should use theme=\"typo3docs\" for proper TYPO3 documentation rendering"
# === MAX RST PAGE LENGTH ===
# `find -exec` is rejected by the runner's dangerous-pattern filter (the
# literal token `exec `), in a one-liner and inside a script body alike, so
# the line count goes through `xargs … wc -l`. `$2 != "total"` drops wc's
# per-batch summary line.
- id: TD-26
type: command
pattern: "find Documentation/ -name '*.rst' -not -path '*/.Build/*' -not -path '*/vendor/*' -not -path '*/node_modules/*' -print0 | xargs -0 -r wc -l | awk '$2 != \"total\" { if ($1 > 250) f = 1 } END { exit f + 0 }'"
severity: info
desc: "RST pages should stay near ~250 lines; split with toctree (NR heuristic — no upstream limit exists)"
provenance: heuristic
source: "Netresearch quality heuristic; not a TYPO3 standard"
# === NO TABS IN RST ===
# The old pattern also globbed `Documentation/**/*.rst`, which needs globstar
# — off in the runner's child shell, so the second operand reached grep as a
# literal path that does not exist.
- id: TD-27
type: command
pattern: "! grep -rqP --include='*.rst' --exclude-dir=.Build --exclude-dir=vendor --exclude-dir=node_modules -- '\\t' Documentation/"
severity: warning
desc: "RST files must use spaces only (4 spaces), never tabs"
# === COMMON DOCUMENTATION SECTIONS ===
- id: TD-15
type: file_exists
target: Documentation/Configuration/
severity: info
desc: "Documentation/Configuration/ directory should exist"
- id: TD-16
type: file_exists
target: Documentation/Installation/
severity: info
desc: "Documentation/Installation/ directory should exist"
- id: TD-17
type: file_exists
target: Documentation/Introduction/
severity: info
desc: "Documentation/Introduction/ directory should exist"
# === DOCUMENTATION ACCURACY ===
# Mirrors scripts/check-guides-xml-version-sync.sh. Both read the attributes
# off the <project> element: a plain `grep -oP 'version="[^"]*"' | head -1`
# first hits the XML declaration's version="1.0", never <project>'s.
- id: TD-30
type: script
command: |
[ -f Documentation/guides.xml ] || exit 0
[ -f ext_emconf.php ] || exit 0
command -v php >/dev/null 2>&1 || exit 0
attrs=$(php -r '$d = new DOMDocument();
if (!@$d->load("Documentation/guides.xml")) { exit(1); }
$p = $d->getElementsByTagNameNS("https://www.phpdoc.org/guides", "project")->item(0);
if ($p === null) { exit(1); }
echo trim($p->getAttribute("version")), "\n", trim($p->getAttribute("release")), "\n";' 2>/dev/null)
# An unparseable guides.xml or a missing <project> is TD-05's finding.
[ -n "$attrs" ] || exit 0
guides_version=$(printf '%s\n' "$attrs" | sed -n 1p)
guides_release=$(printf '%s\n' "$attrs" | sed -n 2p)
emconf_ver=$(grep -oP "'version'\s*=>\s*'[^']*'" ext_emconf.php 2>/dev/null | grep -oP "'[^']*'\$" | tr -d "'")
[ -n "$emconf_ver" ] || exit 0
# SKILL.md and references/guides-xml.md write version="MAJOR.MINOR" and
# release="MAJOR.MINOR.PATCH": release carries the full version, version
# its major.minor. A version equal to the full version is accepted too.
emconf_short=$(printf '%s\n' "$emconf_ver" | cut -d. -f1-2)
errors=0
if [ -n "$guides_version" ] && [ "$guides_version" != "$emconf_short" ] && [ "$guides_version" != "$emconf_ver" ]; then
echo "Version mismatch: guides.xml version=\"$guides_version\" != ext_emconf.php major.minor '$emconf_short' (or full '$emconf_ver')"
errors=1
fi
if [ -n "$guides_release" ] && [ "$guides_release" != "$emconf_ver" ]; then
echo "Release mismatch: guides.xml release=\"$guides_release\" != ext_emconf.php version='$emconf_ver'"
errors=1
fi
exit "$errors"
severity: error
desc: "guides.xml release must equal the ext_emconf.php version and guides.xml version its major.minor (or the full version)"
- id: TD-31
type: command
pattern: "! grep -rqE --exclude-dir=.Build --exclude-dir=vendor --exclude-dir=node_modules -- 'getTranslation|importXliffFile|findByIdentifier|findByComponent' Documentation/"
severity: error
desc: "Documentation must not reference common wrong method names (getTranslation, importXliffFile, findByIdentifier, findByComponent)"
# === DOCUMENTATION COMPLETENESS ===
# Note: TD-41 (versionadded/versionchanged version numbers) removed together
# with check-unreleased-versions.sh — a skipped number is indistinguishable
# from a pending one without the full tag history, and a shallow clone, a
# two-component number and a maintenance-line patch release each warned
# against correct documentation. See rst-syntax.md, "Version Directive
# Accuracy", for why this is left unenforced.
# Note: TD-43 (guides.xml version+release sync) removed — consolidated into TD-30,
# which mirrors check-guides-xml-version-sync.sh (checks both version and release attributes)
# === REQUIRED DOCUMENTATION SECTIONS ===
# Mirrors scripts/check-required-doc-sections.sh.
- id: TD-44
type: script
command: |
[ -d Documentation ] || exit 1
missing=""
for section in Introduction Installation Configuration Usage Developer; do
if [ ! -f "Documentation/$section/Index.rst" ]; then
missing="$missing $section"
fi
done
if [ ! -d Documentation/Troubleshooting ] && [ ! -d Documentation/FAQ ] && [ ! -d Documentation/KnownProblems ]; then
missing="$missing Troubleshooting/FAQ"
fi
is_security=0
if [ -f ext_emconf.php ] && grep -qiP "'category'\s*=>\s*'(security|auth)'" ext_emconf.php 2>/dev/null; then
is_security=1
fi
if [ -f composer.json ] && grep -qiP '"keywords".*\b(security|authentication|encryption)\b' composer.json 2>/dev/null; then
is_security=1
fi
if [ "$is_security" -eq 1 ] && [ ! -d Documentation/Security ]; then
missing="$missing Security(security-related-extension)"
fi
[ -z "$missing" ] && exit 0
echo "Missing documentation sections:$missing"
exit 1
severity: warning
desc: "Documentation should include Introduction, Installation, Configuration, Usage, Developer, and Troubleshooting/FAQ sections"
# === UNTRANSLATED FLUID STRINGS ===
# Mirrors scripts/check-untranslated-fluid-strings.sh. The shipped script
# greps whole lines and then re-greps each attribute out of them; one
# `grep -ohP` over the attribute pattern yields the same set of attributes.
- id: TD-45
type: script
command: |
files=$(find Resources/Private/ -type f -name '*.html' -not -path '*/.Build/*' -not -path '*/vendor/*' -not -path '*/node_modules/*' 2>/dev/null)
[ -n "$files" ] || exit 0
found=0
while IFS= read -r file; do
[ -n "$file" ] || continue
while IFS= read -r attr; do
[ -n "$attr" ] || continue
value=$(printf '%s\n' "$attr" | grep -oP '"[^"]*"' | tr -d '"')
[ -n "$value" ] || continue
if printf '%s\n' "$value" | grep -qP '(f:translate|LLL:|\{.*\})'; then
continue
fi
words=$(printf '%s\n' "$value" | wc -w)
if [ "$words" -gt 3 ]; then
echo "$file: hardcoded string ($words words) in attribute: $value"
found=1
fi
done < <(grep -ohP '(title|aria-label|alt)="[^"]*"' "$file" 2>/dev/null)
done < <(printf '%s\n' "$files")
exit "$found"
severity: warning
desc: "Fluid templates should use f:translate for user-facing text; flag hardcoded English strings (>3 words in title/aria-label/alt)"
# === RST SUBSTITUTIONS: DEFINITIONS MUST REACH THE PAGE ===
# Mirrors scripts/check-rst-substitutions-resolve.sh (the comment there has
# the render evidence).
#
# Inverted 2026-09-28. The earlier TD-46 told Introduction/ and Installation/
# to replace hardcoded values with substitutions from Includes.rst.txt. With
# render-guides 0.40.2 (the digest typo3-ci-workflows' docs.yml pins) a
# substitution defined in an included file does not reach the including page:
# the page shows the literal `|extension_key|` and the render logs
# `app.WARNING: No replacement was found for variable |extension_key|`, for
# `/Includes.rst.txt`, `../Includes.rst.txt` and an included `.rst` alike.
# Following the old advice therefore broke the rendered page. It was also a
# substring match (`nr_repurpose` inside `nr_repurpose_tts`, inside ``literals``)
# that a single use of the substitution silenced for the whole file.
# "Included" means any *.rst.txt and any file an `.. include::` names, whatever
# its suffix, so an included .rst or Shared.txt (both measured failing the same
# way) is covered too. An opening | after an odd number of backslashes is
# escaped and not a reference; after an even number it is (measured as well).
- id: TD-46
type: script
command: |
[ -d Documentation ] || exit 0
# One perl process over the whole tree (xargs could split the list, and an
# include in one batch would then not be seen in another). Definitions count
# as "included" when they sit in a *.rst.txt file or in any file that an
# `.. include::` names, resolved like render-guides does: `/x` from
# Documentation/, anything else relative to the including file.
rc=0
find Documentation \( -name '*.rst' -o -name '*.rst.txt' \) -not -path '*GENERATED*' -print0 \
| perl -0 -MCwd=abs_path -MFile::Basename=dirname -e '
my @files = <STDIN>;
chomp @files;
my $root = abs_path("Documentation");
my (%src, %text);
for my $file (@files) {
open my $fh, "<", $file or next;
local $/ = "\n";
my @lines = <$fh>;
close $fh;
$text{$file} = \@lines;
$src{abs_path($file)} = 1 if $file =~ /\.rst\.txt$/;
for (@lines) {
next unless /^\s*\.\.\s+include::\s+(\S+)/;
my $t = $1;
my $a = abs_path($t =~ m{^/} ? "$root$t" : dirname($file) . "/$t");
$src{$a} = 1 if defined $a && -f $a;
}
}
# Include targets find did not list (Shared.txt, any other suffix) are read
# for their definitions too.
my %have = map { (abs_path($_), 1) } keys %text;
for my $a (grep { !$have{$_} } keys %src) {
open my $fh, "<", $a or next;
local $/ = "\n";
$text{$a} = [<$fh>];
close $fh;
}
my %inc;
for my $file (keys %text) {
next unless $src{abs_path($file)};
for (@{ $text{$file} }) { $inc{$1} = 1 if /^\.\.\s+\|([^|]+)\|\s+\S+::/; }
}
exit 0 unless %inc;
my $found = 0;
for my $file (sort grep { /\.rst$/ } keys %text) {
my (%local, @keep);
my $block = -1; # indent of the line opening a literal block, -1 = none
for my $l (@{ $text{$file} }) {
if ($l =~ /^\.\.\s+\|([^|]+)\|\s+\S+::/) { $local{$1} = 1; next; }
(my $ind = $l) =~ s/^(\s*).*/length($1)/se;
if ($block >= 0) {
if ($l =~ /^\s*$/ || $ind > $block) { next; }
$block = -1;
}
if ($l =~ /^(\s*)\.\.\s+(code-block|code|sourcecode|literalinclude|uml|raw)::/
|| ($l =~ /::\s*$/ && $l !~ /^\s*\.\.\s/)) {
$block = length(($l =~ /^(\s*)/)[0]);
$l =~ s/::\s*$/\n/;
push @keep, $l if $l !~ /^\s*\.\./;
next;
}
if ($l =~ /^(\s*)\.\.(\s|$)/) {
# A comment, i.e. not a directive, target, substitution definition,
# footnote or citation: render-guides drops its indented body.
$block = length($1)
if $l !~ /^\s*\.\.\s+(?:\S+::(?:\s|$)|_|\||\[)/;
next;
}
push @keep, $l;
}
my $text = join "", @keep;
$text =~ s/``.*?``//gs;
$text =~ s/`[^`]*`_{0,2}//gs;
my %seen;
while ($text =~ /(?:(?<![\w|\\])|(?<!\\)(?:\\\\)+\K)\|([^|\s](?:[^|]*[^|\s])?)\|(?=_{0,2}(?![\w|]))/g) {
my $n = $1;
next unless $inc{$n} && !$local{$n} && !$seen{$n}++;
print "$file: |$n| is defined only in an included file and renders as literal text; define it on this page or write the value\n";
$found = 1;
}
}
exit $found;
' || rc=$?
# 1 is a finding. Anything else non-zero is the checker failing; it exits 2
# with the reason on stderr. automated-assessment's run-checkpoints.sh reports
# every non-zero exit of a script as `fail` and discards its output, so there
# a failed scan looks like a finding; only a direct run tells them apart.
case "$rc" in
0) exit 0 ;;
1) exit 1 ;;
*) echo "check-rst-substitutions-resolve: scan failed (perl exit $rc)" >&2; exit 2 ;;
esac
severity: warning
desc: "A page must not use a substitution (|name|) that only an included file such as Includes.rst.txt defines: render-guides does not carry it into the page, which then shows the literal |name|"
# === PLANTUML RENDERING ===
# Inverted 2026-08-14: the earlier version flagged the `uml::` directive on
# the false premise that the toolchain cannot render PlantUML — upstream
# Graphics/Diagrams.html documents it and states PlantUML IS integrated. The
# genuinely broken form is `code-block:: plantuml` (no such highlighter;
# render emits 'Language "plantuml" is not available to highlight code').
#
# The rewrite drops the explanatory `echo`, which was not merely dead weight:
# it contained the two dots of the `uml::` directive spelling, and the runner
# rejects any pattern containing `..` as path traversal. That rejection was
# reported to the user as a plantuml finding on a tree with zero of them.
- id: TD-47
type: command
pattern: "! grep -rqE --exclude-dir=.Build --exclude-dir=vendor --exclude-dir=node_modules -- 'code-block:: *plantuml' Documentation/"
severity: warning
desc: "code-block:: plantuml has no highlighter and fails the render log; use the .. uml:: directive or an SVG figure"
provenance: regression
source: "Render log 'Language \"plantuml\" is not available to highlight code'; uml:: verified rendered per https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Reference/ReStructuredText/Graphics/Diagrams.html"
verified: 2026-08-14
# === DOCUMENTATION QUALITY (relational: the code supplies the denominator) ===
# These four ask whether the documentation matches what the extension declares,
# never how much of it there is, so a small extension can satisfy them fully.
# Each was measured over the 19 documented netresearch t3x-* repositories before
# being adopted; two further candidates were dropped there for measuring nothing
# (see references/documentation-quality-checks.md).
#
# Mirrors scripts/check-settings-documented.sh.
- id: TD-52
type: script
command: |
[ -f ext_conf_template.txt ] || exit 0
[ -d Documentation ] || exit 0
missing=""
count=0
while IFS= read -r key; do
[ -n "$key" ] || continue
count=$((count + 1))
# A direct file grep, never `printf … | grep -q`: that pipeline inverts
# under pipefail once the input passes the pipe buffer.
if ! grep -rqF --exclude-dir=.Build --exclude-dir=vendor --exclude-dir=node_modules -- "$key" Documentation/ 2>/dev/null; then
missing="$missing $key"
fi
done < <(sed -e 's/#.*$//' ext_conf_template.txt | grep -oE '^[A-Za-z][A-Za-z0-9_.]*[[:space:]]*=' | sed -e 's/[[:space:]]*=$//' | sort -u)
[ "$count" -eq 0 ] && exit 0
[ -z "$missing" ] && exit 0
echo "Settings declared in ext_conf_template.txt but not mentioned in Documentation/:$missing"
echo " ($count declared; document each one, ideally as a confval so it is typed and linkable)"
exit 1
severity: warning
desc: "every setting declared in ext_conf_template.txt is mentioned in Documentation/"
provenance: heuristic
source: "Netresearch quality criterion; measured 0-100% across 11 t3x repos with settings"
verified: 2026-08-19
# Mirrors scripts/check-confval-completeness.sh.
- id: TD-53
type: script
command: |
report=$(find Documentation -name '*.rst' -not -path '*/.Build/*' -not -path '*/vendor/*' -not -path '*/node_modules/*' -print0 2>/dev/null \
| xargs -0 -r awk '
# A confval block runs until the next directive at the same or lower
# indent, or a line at column 0 that is not blank.
function flush() {
if (in_block) {
if (!(has_type && has_default)) {
missing = (has_type ? "" : ":type: ") (has_default ? "" : ":default:")
printf "%s:%d: confval %s lacks %s\n", file, start, name, missing
}
}
in_block = 0; has_type = 0; has_default = 0
}
FNR == 1 { flush(); file = FILENAME }
match($0, /^[[:space:]]*\.\.[[:space:]]+confval::[[:space:]]*/) {
flush()
in_block = 1; start = FNR
name = substr($0, RSTART + RLENGTH)
sub(/[[:space:]].*$/, "", name)
next
}
in_block && /^[[:space:]]*:type:/ { has_type = 1 }
in_block && /^[[:space:]]*:[Dd]efault:/ { has_default = 1 }
in_block && /^[[:space:]]*\.\.[[:space:]]+[a-zA-Z:]+::/ { flush() }
in_block && /^[^[:space:]]/ && !/^\.\./ { flush() }
END { flush() }
')
[ -z "$report" ] && exit 0
echo "$report"
n=$(printf '%s\n' "$report" | grep -c ':')
echo " $n confval block(s) without :type: and/or :default: — state both so the reader"
echo " does not have to open the code to learn what a value may be"
exit 1
severity: warning
desc: "every confval states both :type: and :default: — depth per option instead of number of options"
provenance: heuristic
source: "Netresearch quality criterion; measured 20-100% across 15 t3x repos with confvals"
verified: 2026-08-19
# Mirrors scripts/check-ui-surface-screenshots.sh, except that the module
# count is greped rather than obtained by `@include`ing the audited
# Modules.php — see the comment in the body.
- id: TD-54
type: script
command: |
[ -d Documentation ] || exit 0
modules=0
estimated=""
if [ -f Configuration/Backend/Modules.php ]; then
# Counted by pattern, never executed. The shipped script `@include`s
# this file; the repository under assessment is not trusted input, and
# a Modules.php can require other files, open connections or write to
# disk. Every other check here parses only, and this is the one
# divergence from scripts/check-ui-surface-screenshots.sh.
#
# Three registration shapes, each anchored so that nested property
# lines at deeper indentation are never counted: a top-level key of a
# returning array at one indent level (single- or double-quoted), the
# same key on a compact single-line `return [...]`, and old-style
# addModule(). The compact branch counts lines, so a one-liner
# declaring two modules reports 1 — only zero-vs-nonzero decides this
# check, so the undercount is harmless and the label says "estimated".
modules=$({ grep -cE "addModule|^ {4}['\"][A-Za-z0-9_]+['\"] *=>|return \[['\"][A-Za-z0-9_]+['\"] *=>" Configuration/Backend/Modules.php 2>/dev/null || true; } | head -1)
modules=${modules:-0}
estimated=" (estimated: registrations counted by pattern, not executed)"
fi
plugins=0
if [ -d Configuration/TCA/Overrides ]; then
# `grep` exits 1 when it matches nothing, and under `set -e` with
# `pipefail` that killed the shipped script before it reached the image
# count — a silent exit 1 that reads as a finding.
plugins=$({ grep -rhoE 'registerPlugin|addPlugin' Configuration/TCA/Overrides/ 2>/dev/null || true; } | wc -l)
fi
surfaces=$((modules + plugins))
[ "$surfaces" -gt 0 ] || exit 0
images=0
for dir in Documentation/Images Documentation/_Images; do
[ -d "$dir" ] || continue
found=$({ find "$dir" -type f \( -iname '*.png' -o -iname '*.avif' -o -iname '*.jpg' -o -iname '*.jpeg' -o -iname '*.gif' -o -iname '*.webp' \) 2>/dev/null || true; } | wc -l)
images=$((images + found))
done
[ "$images" -gt 0 ] && exit 0
echo "This extension registers $surfaces user-interface surface(s)$estimated but Documentation/ has no screenshot."
echo " A reader cannot tell what the module or plugin looks like before installing it."
exit 1
severity: warning
desc: "an extension registering a backend module or frontend plugin shows it at least once; only the zero case, because how many screenshots are enough is not mechanically decidable"
provenance: heuristic
source: "Netresearch quality criterion; fires on 8 of 13 t3x repos with a UI surface"
verified: 2026-08-19
# Mirrors scripts/check-screenshot-freshness.sh. The 200-line threshold is
# calibrated, not invented: across the netresearch t3x fleet the observed
# magnitudes were 37 lines for the one current repository and 255 to 1354 for
# the rest. It sits in the gap, not at either edge.
- id: TD-55
type: script
command: |
[ -d Documentation ] || exit 0
git rev-parse --git-dir >/dev/null 2>&1 || exit 0
# A shallow clone or a --no-tags CI checkout knows a truncated history, and
# the comparison would describe the checkout rather than the repository.
[ "$(git rev-parse --is-shallow-repository 2>/dev/null)" = "true" ] && exit 0
image_dir=""
for dir in Documentation/Images Documentation/_Images; do
[ -d "$dir" ] || continue
if find "$dir" -type f \( -iname '*.png' -o -iname '*.avif' -o -iname '*.jpg' -o -iname '*.jpeg' -o -iname '*.gif' -o -iname '*.webp' \) 2>/dev/null | grep -q .; then
image_dir="$dir"
break
fi
done
# No screenshots at all is TD-54's business, not this check's.
[ -n "$image_dir" ] || exit 0
visual=""
for p in Resources/Private/Templates Resources/Private/Partials Resources/Public; do
[ -e "$p" ] && visual="$visual $p"
done
[ -n "$visual" ] || exit 0
last_image=$(git log -1 --format=%H -- "$image_dir" 2>/dev/null)
[ -n "$last_image" ] || exit 0
changed=$(git diff --shortstat "$last_image" HEAD -- $visual 2>/dev/null)
lines=$(printf '%s' "$changed" | grep -oE '[0-9]+ (insertion|deletion)' | grep -oE '^[0-9]+' | paste -sd+ -)
total=$(( ${lines:-0} + 0 ))
[ "$total" -le 200 ] && exit 0
days=$(( ( $(git log -1 --format=%ct HEAD) - $(git log -1 --format=%ct "$last_image") ) / 86400 ))
echo "Templates and public assets changed by $total lines since the newest screenshot (${days} days ago)."
echo " Re-take the screenshots that show those surfaces, or confirm they still match."
exit 1
severity: info
desc: "templates and public assets have not changed substantially since the newest screenshot — an outdated screenshot is worse than a missing one"
provenance: heuristic
source: "Netresearch quality criterion; 5 of 6 t3x repos with screenshots currently miss it, which is what a bonus indicator is for"
verified: 2026-08-19
# === UNSUPPORTED LITERALINCLUDE OPTIONS ===
# Same rewrite as TD-47, same history: the `head -1 && echo … && exit 1` shape
# reported literalinclude line options on a tree containing none.
- id: TD-51
type: command
pattern: "! grep -rqE --exclude-dir=.Build --exclude-dir=vendor --exclude-dir=node_modules -- ':(lines|start-after|end-before|start-at|end-at):' Documentation/"
severity: warning
desc: "literalinclude line-selection options (:lines:, :start-after:, :end-before:) are not implemented by the TYPO3 renderer and are silently ignored"
provenance: regression
source: "https://github.com/TYPO3-Documentation/TYPO3CMS-Guide-HowToDocument/pull/547 (closed after renderer-source check); precedent #490 / render-guides#974"
learning_id: retro-20260814-literalinclude-renderer-gap
verified: 2026-08-14
# === CHANGELOG VERSION COVERAGE ===
# Mirrors scripts/check-changelog-version-coverage.sh. The shipped script runs
# two tag greps in a brace group; `^v?\d+\.\d+` with the `v` stripped
# afterwards selects the same set. It diverges in one place: an RST changelog
# is also matched on the bare version — see the comment in the loop.
- id: TD-48
type: script
command: |
changelog=""
for f in CHANGELOG.md Changelog.md changelog.md Documentation/ChangeLog/Index.rst; do
if [ -f "$f" ]; then
changelog="$f"
break
fi
done
if [ -z "$changelog" ]; then
echo "No changelog file found"
exit 1
fi
tags=$(git tag -l 2>/dev/null | grep -P '^v?\d+\.\d+' | sed 's/^v//')
[ -n "$tags" ] || exit 0
missing=""
while IFS= read -r version; do
[ -n "$version" ] || continue
# `[1.2.0]` is the Keep-a-Changelog spelling, and it is a Markdown
# convention. An RST changelog writes the version as a section heading
# — `1.2.0` over an underline, or `Version 1.2.0` — so requiring the
# brackets reported every tag as missing for a project using the
# Documentation/ChangeLog/Index.rst candidate accepted above. Accept
# the bare version for an RST changelog only, bounded by non-version
# characters so `1.2.0` is not satisfied by `11.2.0` or `1.2.01`.
# This is the one divergence from
# scripts/check-changelog-version-coverage.sh.
case "$changelog" in
*.rst)
esc=$(printf '%s' "$version" | sed 's/\./\\./g')
if grep -qE -- "(^|[^0-9.])${esc}([^0-9.]|$)" "$changelog" 2>/dev/null; then
continue
fi
;;
esac
# The `v` may sit INSIDE the brackets: `## [v2.19.1](…/tag/v2.19.1)`
# is as common across the fleet as `## [2.19.1]`, and a literal search
# for one spelling reported every heading of the other kind as missing.
# Two fixed strings rather than a regex: a legal tag may contain `(`,
# `{` or `$`, which a pattern would either mis-escape or mis-match.
if ! grep -qF -e "[$version]" -e "[v$version]" "$changelog" 2>/dev/null; then
missing="$missing $version"
fi
done < <(printf '%s\n' "$tags")
[ -z "$missing" ] && exit 0
echo "Versions missing from $changelog:$missing"
exit 1
severity: warning
desc: "CHANGELOG.md should have entries for all git tags between initial and current version"
# === ADR COVERAGE ===
# Mirrors scripts/check-adr-coverage.sh.
- id: TD-49
type: script
command: |
[ -d Classes ] || exit 0
class_count=$(find Classes/ -type f -name '*.php' -not -path '*/.Build/*' -not -path '*/vendor/*' -not -path '*/node_modules/*' 2>/dev/null | wc -l)
[ "$class_count" -gt 10 ] || exit 0
if [ -d Documentation/Developer/Adr ] || [ -d Documentation/Developer/ADR ] || [ -d Documentation/Adr ] || [ -d Documentation/ADR ] || [ -d docs/adr ]; then
exit 0
fi
echo "Extension has $class_count classes but no ADR directory (Documentation/Developer/Adr/)"
echo "Significant architectural decisions should be documented as Architecture Decision Records"
exit 1
severity: info
desc: "Extensions with >10 classes should have Documentation/Developer/Adr/ for significant architectural decisions"
llm_reviews:
# === CONTENT QUALITY ===
- id: TD-20
domain: documentation
prompt: |
Review the Documentation/Index.rst file for:
- Proper RST formatting with correct heading levels
- Clear project description in the introduction
- Logical toctree ordering (Introduction, Installation, Configuration, etc.)
- Appropriate maxdepth setting in toctree
Report any formatting issues or missing standard sections.
severity: warning
desc: "Index.rst should have proper structure and formatting"
- id: TD-21
domain: documentation
prompt: |
Compare README.md with Documentation/Index.rst:
- Extension name should be consistent
- Version references should match
- Feature descriptions should align
- Installation instructions should not contradict
Report any inconsistencies between these files.
severity: warning
desc: "README.md and Documentation should be consistent"
- id: TD-22
domain: documentation
prompt: |
Review the guides.xml configuration for:
- Correct project name matching extension key
- Appropriate release/version values
- Valid copyright statement
- Proper vendor and extension settings
Check against TYPO3 documentation rendering requirements.
severity: warning
desc: "guides.xml should be properly configured for docs.typo3.org"
- id: TD-23
domain: documentation
prompt: |
Check documentation completeness:
- Installation instructions with composer and TER options
- Configuration reference for TypoScript/FlexForm settings
- Usage examples with code snippets
- Changelog or version history
Report missing critical sections for an extension user.
severity: info
desc: "Documentation should cover installation, configuration, and usage"
- id: TD-24
domain: documentation
prompt: |
Review RST file naming conventions:
- Files should use CamelCase (Configuration.rst, not configuration.rst)
- Index.rst is the exception (lowercase allowed)
- Directory names should also follow CamelCase
List any files not following the convention.
severity: info
desc: "RST files should follow TYPO3 CamelCase naming convention"
# === DOCUMENTATION ACCURACY ===
- id: TD-32
domain: documentation
prompt: |
Review Documentation/Configuration/Index.rst (and any TypoScript configuration docs) for backend module TypoScript usage.
Backend modules MUST use the `module.` prefix in TypoScript, NOT `plugin.`.
Check for patterns like:
- `plugin.tx_extensionname` used for backend module configuration (WRONG)
- Should be `module.tx_extensionname` for backend modules
Report any instances where `plugin.` prefix is used for backend module TypoScript configuration.
severity: warning
desc: "TypoScript docs must use module. prefix (not plugin.) for backend modules"
- id: TD-33
domain: documentation
prompt: |
Compare CLI command documentation against the actual ImportCommand (or other Command classes) configure() method.
For each documented CLI command:
1. Find the corresponding Command class in Classes/Command/
2. Read its configure() method to get actual arguments and options
3. Compare documented arguments/options against actual configure() definitions
4. Check that argument names, option names, descriptions, and required/optional status match
Report any mismatches between documented CLI arguments and actual Command::configure() definitions.
severity: error
desc: "CLI command documentation must match actual Command::configure() arguments"
- id: TD-40
domain: documentation
prompt: |
Check Documentation/ChangeLog/Index.rst (or similar changelog file) against git tags.
1. List all git tags with `git tag -l`
2. For each tag that represents a release version, verify it appears in the changelog
3. Check that changelog entries are in reverse chronological order
Report any git tags (release versions) missing from the changelog documentation.
severity: warning
desc: "ChangeLog should include entries for all git tags (release versions)"
- id: TD-42
domain: documentation
prompt: |
Check all Documentation sections that should contain screenshots (especially for backend modules, configuration screens, and UI workflows).
Look for:
- Sections with TODO placeholders instead of actual content
- Screenshot references (.. figure::) pointing to non-existent images
- Sections titled "Screenshots" or similar that are empty or contain only placeholder text
- Backend module documentation lacking any screenshots
Report any sections with missing or placeholder screenshot content.
severity: medium
desc: "Screenshots sections should have actual content, not TODO placeholders"
# === API EXAMPLE ACCURACY ===
- id: TD-50
domain: documentation
prompt: |
Compare code examples in README.md and Documentation/ RST files against the actual codebase.
For each code example that references PHP classes, methods, or functions:
1. Find the actual class in Classes/ directory
2. Verify the method signatures match (method name, parameters, return types)
3. Check that convenience methods shown in examples actually exist
4. Verify namespace and use statements are correct
Report any code examples that reference methods or signatures that don't exist in the codebase.
severity: error
desc: "Code examples in README.md and docs must use actual method signatures from the codebase"
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |