TYPO3 Site / Project Conformance Skill

Conformance and hardening for deployable TYPO3 v14 site/project repositories — the site/project counterpart to the extension-scoped typo3-conformance.

What this skill solves

TYPO3 work splits into two worlds: reusable extensions (packages, ext_emconf.php, Classes/, TER) and deployable sites (type: project, Docker/Compose, CI/CD, secrets, runtime). The existing conformance skill covers extensions; this one covers the site/project half — repository layout, container topology, Concourse pipeline, supply-chain gating, secret handling, and the Valkey/ofelia runtime — against the Netresearch gold standard.

The ruleset

The rule catalogue and a self-contained checker ship inside this skill, so running it needs nothing else:

skills/typo3-site-conformance/checker/rules.json — the machine-readable rule catalogue (generated by gen_rules.py).
skills/typo3-site-conformance/checker/check.py — python3 check.py <repo-path> (only pyyaml required).

typo3-14-gold is a runnable reference implementation that scores 100 % against this ruleset; typo3-project-standard is the human-readable companion. Both are Netresearch-internal and optional.

Use when

A repository has composer.json "type": "project" and a root Compose file (compose.yaml/docker-compose.yml).
You are reviewing or hardening container/Compose topology, a Concourse pipeline, supply-chain gating, or TYPO3 site config (config/system, config/sites).
You are forking the gold skeleton to start a new customer site, or migrating a legacy support/typo3-NN/app-style repo.

For extension repos use typo3-conformance instead.

Expected outputs

A pass/fail conformance verdict per rule family (STRUCT, CONTAINER, CI, DEPLOY, DEP, SEC, DOC) with file:line evidence.
A prioritized remediation list (ERROR blocks, WARN should-fix, INFO advisory).
For migrations: the concrete seven-move transformation plan (references/migration-from-reference.md).

Context requirements

Read access to the target repository tree (composer.json, Dockerfile, compose*.yaml, ci/, config/system, config/sites, .gitlab-ci.yml, AGENTS.md).
python3 + pyyaml to run the bundled checker. Nothing else.

Example prompts

"Is this TYPO3 site repo gold-conformant? Score it."
"Review our compose.yaml and Concourse pipeline against the gold standard."
"Migrate this support/typo3-12/app repo to the gold layout."
"Why is check.py failing on STRUCT-001 / SC-007?"

Related skills

typo3-conformance — extension quality/TER readiness (the sibling).
enterprise-readiness — generic supply-chain/OpenSSF hardening.
docker-development, concourse-ci — the underlying container/CI mechanics.

Compatibility

TYPO3 v14.3 LTS (current gold target), PHP 8.4 baseline. Reference implementation (Netresearch-internal): typo3-14-gold.

Installation

Add the Netresearch marketplace and install the plugin:

/plugin marketplace add netresearch/claude-code-marketplace
/plugin install typo3-site-conformance

Contributing

Issues and PRs welcome. To change a rule, edit the catalogue in skills/typo3-site-conformance/checker/gen_rules.py and regenerate rules.json. Run bash validate-skill.sh . (from skill-repo-skill) and the tests below before opening a PR. A change to check.py or gen_rules.py comes with a test in tests/test_check.py that fails without it: for a new or changed rule, add its mutation to MUTATIONS and keep the gold fixture passing.

The components and the checker's data flow are described in docs/ARCHITECTURE.md. AGENTS.md is the index for coding agents.

Tests

python3 tests/test_check.py        # needs Python 3 and PyYAML; exit 0 = all passed

tests/test_check.py is a standard-library unittest suite. It builds a "gold" fixture repository in a temporary directory (with git) and checks that:

every repo-scope rule passes on the fixture, and check.py exits 0 with a 100 % score;
one mutation per rule makes that rule fail, and check.py exits 1 and names it;
the refinements in checker/README.md hold (app/ layout, job services, comment-only keywords, unreferenced anchors, tracked .env, vendored assets, malformed pipelines, non-UTF-8 files);
the helpers (image pinning, secret detection, placeholder expansion) behave as documented;
rules.json is what gen_rules.py generates and matches its pinned hash.

A failure names the test and, for a mutation, the rule code and the detail the check returned (SC-002 still passes: …). The skill instructions and references are text and are covered by the validators, not by these tests.

CI runs the suite in .github/workflows/tests.yml (Skill Tests) on every pull request and every push to main, through the skill-repo-skill tests workflow, with the runner's python3.

Dependencies

Runtime: the checker needs Python 3 and PyYAML, declared in the PEP 723 block at the top of check.py; uv run check.py <repo> installs it. git is used when present (without it, DRO-011 relies on the .gitignore text alone, STRUCT-006 skips its tracked-.env test and the vendoring rule SC-016 is skipped). gen_rules.py and the tests use the standard library, plus PyYAML for the tests.
Composer: composer.json requires netresearch/composer-agent-skill-plugin, which installs the skill into a Composer project. There is no lock file; the package is consumed as a library.
CI: the workflows call shared workflows in netresearch/skill-repo-skill, netresearch/.github and (security.yml) netresearch/typo3-ci-workflows by @main; those pin third-party actions by commit SHA and tools (ruff, ShellCheck, PyYAML) by version.
Updates: Renovate (renovate.json, config:recommended) opens update pull requests; Dependabot security updates are enabled for the repository. auto-merge-deps.yml approves and enables auto-merge for pull requests opened by renovate[bot] or dependabot[bot] without the deps-major or deps-no-automerge label; it passes the shared workflow the PROJECT_APP_ID and PROJECT_APP_PRIVATE_KEY secrets. A new dependency is added only when the standard library cannot do the job, and is declared where its consumer reads it (the PEP 723 block for the checker, composer.json for Composer).

Governance and policies

This repository follows the Netresearch organisation policies:

Governance: ownership, roles, and how decisions are made and disputes resolved.
Roadmap: planned and explicitly excluded work for the coming year.
Handling of dependency and code analysis findings: thresholds, deadlines and the exception process for dependency (SCA) and static analysis (SAST) findings.
Secret management: how CI and release credentials are stored, accessed and rotated.
Access roster: who holds administrative access to this repository and the organisation.

The security assurance case for this skill (threat model, trust boundaries, countermeasures and limits) is in docs/SECURITY-ASSURANCE.md.

Checks that run on pull requests in this repository:

Skill Validation (lint.yml): skill structure, manifest sync, markdownlint, yamllint, actionlint, JSON syntax, ShellCheck at severity style, ruff check and ruff format, checkpoint schema.
Eval Validation (eval-validate.yml) and Skill Tests (tests.yml).
Security (security.yml): Betterleaks secret scanning of the git history, zizmor on the workflow files, Dependency Review (pull requests only), and Composer Audit plus Opengrep SAST through the shared workflow in netresearch/typo3-ci-workflows. The SAST rules are in the organisation's static analysis rule.
Template Drift (check-template-drift.yml): fails when a file governed by the skill template differs from it; .github/template.yaml lists the intentional exception (lint.yml).
Harness Verification (harness-verify.yml): checks AGENTS.md through the skill-repo-skill reusable workflow.
Labeler (labeler.yml): applies labels from .github/labeler.yml on pull_request_target through a shared workflow in netresearch/.github, without checking out pull request code.
DCO: every commit carries a Signed-off-by trailer.
CodeQL default setup (a repository setting, not a workflow file) analyses the GitHub Actions workflows and the Python code with the extended query suite.
SonarCloud analysis (configured outside the workflows); on pull requests to main that are not drafts, also the CodeRabbit review and the Copilot code review that the repository ruleset requests.
Auto-merge dependency PRs (auto-merge-deps.yml), which acts only on Renovate and Dependabot pull requests.

OpenSSF Scorecard (scorecard.yml) does not run on pull requests: it runs on pushes to main and master, weekly and on manual dispatch. GitHub secret scanning with push protection is enabled for this repository in addition to the Betterleaks scan.

netresearch/typo3-site-conformance