Skip to content

netresearch/typo3-docs-skill / skills/typo3-docs

typo3-docs

Flagged

Use 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+).

FileKindSize
SKILL.mdskill md5.9 KB
assets/AGENTS.mdmarkdown11.7 KB
assets/guides.xml.distother1.8 KB
checkpoints.yamlconfig43.1 KB
evals/evals.jsonconfig23.1 KB
references/architecture-decision-records.mdmarkdown6.6 KB
references/asset-templates-guide.mdmarkdown2.8 KB
references/canonical-sources.mdmarkdown6.2 KB
references/code-structure-elements.mdmarkdown7.4 KB
references/coding-guidelines.mdmarkdown7.1 KB
references/content-directives.mdmarkdown7.6 KB
references/documentation-coverage-analysis.mdmarkdown7.6 KB
references/documentation-quality-checks.mdmarkdown3.5 KB
references/extraction-patterns.mdmarkdown23.3 KB
references/file-structure.mdmarkdown7.0 KB
references/guides-xml.mdmarkdown15.9 KB
references/intercept-deployment.mdmarkdown12.5 KB
references/render-guides-development.mdmarkdown8.8 KB
references/rendering.mdmarkdown17.3 KB
references/rst-syntax.mdmarkdown10.5 KB
references/screenshots.mdmarkdown13.1 KB
references/scripts-guide.mdmarkdown3.1 KB
references/text-roles-inline-code.mdmarkdown2.5 KB
references/typo3-directives.mdmarkdown16.0 KB
references/typo3-extension-architecture.mdmarkdown17.4 KB
references/upstream-docs-contribution.mdmarkdown7.5 KB
scripts/add-agents-md.shexecutablescript2.2 KB
scripts/analyze-docs.shexecutablescript12.0 KB
scripts/check-adr-coverage.shexecutablescript778 B
scripts/check-changelog-version-coverage.shexecutablescript1.7 KB
scripts/check-confval-completeness.shexecutablescript2.1 KB
scripts/check-guides-xml-schema.shexecutablescript4.0 KB
scripts/check-guides-xml-version-sync.shexecutablescript1.9 KB
scripts/check-required-doc-sections.shexecutablescript1.6 KB
scripts/check-rst-substitutions-resolve.shexecutablescript5.4 KB
scripts/check-screenshot-freshness.shexecutablescript2.5 KB
scripts/check-settings-documented.shexecutablescript1.5 KB
scripts/check-ui-surface-screenshots.shexecutablescript2.8 KB
scripts/check-untranslated-fluid-strings.shexecutablescript1.6 KB
scripts/check-version-match.shexecutablescript624 B
scripts/extract-all.shexecutablescript4.1 KB
scripts/extract-build-configs.shexecutablescript2.8 KB
scripts/extract-composer.shexecutablescript1.9 KB
scripts/extract-extension-config.shexecutablescript5.0 KB
scripts/extract-php.shexecutablescript5.1 KB
scripts/extract-project-files.shexecutablescript2.0 KB
scripts/extract-repo-metadata.shexecutablescript4.7 KB
scripts/extraction-dir.shexecutablescript1.7 KB
scripts/json-string.shscript921 B
scripts/render_docs.shexecutablescript1.0 KB
scripts/validate_docs.shexecutablescript6.2 KB
scripts/validate_headings.pyexecutablescript4.4 KB

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"
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 322kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 119kUpdated Claude CodeCodexVerifiedInstall
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: 118kUpdated Claude CodeCodexVerifiedInstall