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

references/architecture-decision-records.md

View on GitHub
<!-- SPDX-License-Identifier: CC-BY-SA-4.0 -->
<!-- SPDX-FileCopyrightText: Netresearch DTT GmbH -->

# Architecture Decision Records (ADRs)

`[skill-procedure]` — ADR practice for TYPO3 extension documentation (not an
upstream TYPO3 topic; pattern derived from nr_llm).
**Purpose:** Document architectural decisions with context and consequences

## Overview

Architecture Decision Records capture important architectural decisions along with their context and consequences. They provide a historical record of why certain decisions were made, helping future maintainers understand the codebase.

## When to Write an ADR

- Major architectural changes (new patterns, frameworks, approaches)
- Technology choices (libraries, APIs, protocols)
- Significant refactoring decisions
- Security-relevant decisions
- Performance optimization strategies
- Deprecation of existing patterns

## Directory Structure

ADRs live where checkpoint TD-49 (`scripts/check-adr-coverage.sh`) looks for
them: `Documentation/Developer/Adr/` (preferred; `Documentation/Developer/ADR/`,
`Documentation/Adr/`, `Documentation/ADR/` and `docs/adr/` are also accepted).
Do not place them in
`Documentation/DeveloperGuide/ArchitectureDecisions/` or `claudedocs/` — those
paths fail the skill's own coverage check.

```
Extension/
├── Documentation/
│   └── Developer/
│       └── Adr/
│           ├── Index.rst                        # Links to ADRs
│           ├── Adr001InitialArchitecture.rst
│           └── Adr013ApiKeyEncryption.rst
└── README.md
```

## ADR Format

### Standard Template

```markdown
# ADR-NNN: Title

## Status

[Proposed | Accepted | Deprecated | Superseded by ADR-XXX]

## Context

What is the issue that we're seeing that is motivating this decision or change?

## Decision

What is the change that we're proposing and/or doing?

## Consequences

What becomes easier or more difficult to do because of this change?

### Positive
- Benefit 1
- Benefit 2

### Negative
- Tradeoff 1
- Tradeoff 2

### Neutral
- Side effect 1
```

### Extended Template (Recommended)

```markdown
# ADR-NNN: Descriptive Title

## Status

Accepted

## Date

2024-12-30

## Context

Describe the forces at play, including technical, political, social, and
project local. These forces are probably in tension.

## Problem Statement

Clear statement of the specific problem being solved.

## Decision Drivers

- Driver 1: What factors influenced this decision?
- Driver 2: Performance requirements?
- Driver 3: Security considerations?
- Driver 4: Maintainability concerns?

## Considered Options

### Option 1: [Name]
**Description:** Brief explanation

**Pros:**
- Advantage 1
- Advantage 2

**Cons:**
- Disadvantage 1
- Disadvantage 2

### Option 2: [Name]
**Description:** Brief explanation

**Pros:**
- Advantage 1

**Cons:**
- Disadvantage 1

## Decision

We chose Option 1 because...

## Implementation Details

```php
// Code example showing the decided approach
```

## Consequences

### Positive
- What becomes easier

### Negative
- What becomes harder

### Risks
- Potential issues to watch for

## Related Decisions

- ADR-005: Related decision
- ADR-012: Prerequisite decision

## References

- [External documentation](https://example.com)
- [TYPO3 documentation](https://docs.typo3.org)
```

## Example ADRs

Full worked examples (security-decision and configuration-hierarchy ADRs
following the extended template) live in the nr_llm extension:
https://github.com/netresearch/t3x-nr-llm — `Documentation/Developer/Adr/`.
This file deliberately does not duplicate them; use the templates above.

## Best Practices

### Naming Conventions

- Format: `ADR-NNN-kebab-case-title.md`
- Numbers: Zero-padded, sequential (001, 002, 003)
- Title: Descriptive, action-oriented

### Content Guidelines

1. **Be specific** - Include code examples, not just concepts
2. **Document alternatives** - Show what wasn't chosen and why
3. **Include dates** - Decisions have context in time
4. **Link related ADRs** - Build a decision graph
5. **Update status** - Mark deprecated/superseded decisions

### RST Integration

```rst
.. toctree::
   :maxdepth: 2
   :caption: Architecture Decisions

   Adr/Adr001InitialArchitecture
   Adr/Adr012ApiKeyEncryption
   Adr/Adr013ThreeLevelConfiguration
```

### One Set of ADRs, Not Two

Keep ADRs only in `Documentation/Developer/Adr/` (rendered, checked by
TD-49). Do not maintain a parallel Markdown set under `claudedocs/` — two
copies drift, and agents read the rendered documentation source anyway.

## ADR Lifecycle

```
┌──────────┐     ┌──────────┐     ┌────────────┐
│ Proposed │ ──▶ │ Accepted │ ──▶ │ Deprecated │
└──────────┘     └──────────┘     └────────────┘
                      │                  │
                      │                  ▼
                      │           ┌────────────────┐
                      └─────────▶ │ Superseded by  │
                                  │   ADR-XXX      │
                                  └────────────────┘
```

## Tools and Automation

### Generate ADR Index

```bash
#!/bin/bash
# scripts/generate-adr-index.sh

echo "# Architecture Decision Records" > docs/adr/README.md
echo "" >> docs/adr/README.md
echo "| ADR | Title | Status |" >> docs/adr/README.md
echo "|-----|-------|--------|" >> docs/adr/README.md

for file in docs/adr/ADR-*.md; do
    number=$(basename "$file" | grep -oP 'ADR-\d+')
    title=$(head -1 "$file" | sed 's/# //')
    status=$(grep -m1 "^## Status" -A2 "$file" | tail -1)
    echo "| [$number]($file) | $title | $status |" >> docs/adr/README.md
done
```

### ADR Template Script

```bash
#!/bin/bash
# scripts/new-adr.sh

NEXT_NUM=$(ls docs/adr/ADR-*.md 2>/dev/null | wc -l)
NEXT_NUM=$((NEXT_NUM + 1))
PADDED=$(printf "%03d" $NEXT_NUM)

TITLE="${1:-untitled}"
SLUG=$(echo "$TITLE" | tr '[:upper:]' '[:lower:]' | tr ' ' '-')
FILENAME="docs/adr/ADR-${PADDED}-${SLUG}.md"

cat > "$FILENAME" << EOF
# ADR-${PADDED}: ${TITLE}

## Status

Proposed

## Date

$(date +%Y-%m-%d)

## Context

[Describe the context]

## Decision

[Describe the decision]

## Consequences

### Positive
-

### Negative
-
EOF

echo "Created: $FILENAME"
```

## Related References

- [Michael Nygard's ADR format](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions)
- [ADR Tools](https://github.com/npryce/adr-tools)
- `rst-syntax.md` - RST formatting for TYPO3 docs
- `typo3-extension-architecture.md` - Extension structure
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