@synapta/skills 0.1.1 → 0.2.0

package/skills/repo-bootstrap/references/examples/t3x-rte-ckeditor-image/Classes-AGENTS.md

@@ -0,0 +1,392 @@
+# Classes/AGENTS.md
+
+<!-- Managed by agent: keep sections & order; edit content, not structure. Last updated: 2025-10-15 -->
+
+**Scope:** PHP backend components (Controllers, EventListeners, DataHandling, Utils)
+**Parent:** [../AGENTS.md](../AGENTS.md)
+
+## 📋 Overview
+
+PHP backend implementation for TYPO3 CKEditor Image extension. Components:
+
+### Controllers
+- **SelectImageController** - Image browser wizard, file selection, image info API
+- **ImageRenderingController** - Image rendering and processing for frontend
+- **ImageLinkRenderingController** - Link-wrapped image rendering
+
+### EventListeners
+- **RteConfigurationListener** - PSR-14 event for RTE configuration injection
+
+### DataHandling
+- **RteImagesDbHook** - Database hooks for image magic reference handling
+- **RteImageSoftReferenceParser** - Soft reference parsing for RTE images
+
+### Backend Components
+- **RteImagePreviewRenderer** - Backend preview rendering
+
+### Utilities
+- **ProcessedFilesHandler** - File processing and manipulation utilities
+
+## 🏗️ Architecture Patterns
+
+### TYPO3 Patterns
+- **FAL (File Abstraction Layer):** All file operations via ResourceFactory
+- **PSR-7 Request/Response:** HTTP message interfaces for controllers
+- **PSR-14 Events:** Event-driven configuration and hooks
+- **Dependency Injection:** Constructor-based DI (TYPO3 v13+)
+- **Service Configuration:** `Configuration/Services.yaml` for DI registration
+
+### File Structure
+```
+Classes/
+├── Backend/
+│   └── Preview/
+│       └── RteImagePreviewRenderer.php
+├── Controller/
+│   ├── ImageLinkRenderingController.php
+│   ├── ImageRenderingController.php
+│   └── SelectImageController.php
+├── DataHandling/
+│   └── SoftReference/
+│       └── RteImageSoftReferenceParser.php
+├── Database/
+│   └── RteImagesDbHook.php
+├── EventListener/
+│   └── RteConfigurationListener.php
+└── Utils/
+    └── ProcessedFilesHandler.php
+```
+
+## 🔧 Build & Tests
+
+```bash
+# PHP-specific quality checks
+make lint                      # All linters (syntax + PHPStan + Rector + style)
+composer ci:test:php:lint      # PHP syntax check
+composer ci:test:php:phpstan   # Static analysis
+composer ci:test:php:rector    # Rector modernization check
+composer ci:test:php:cgl       # Code style check
+
+# Fixes
+make format                    # Auto-fix code style
+composer ci:cgl               # Alternative: fix style
+composer ci:rector            # Apply Rector changes
+
+# Full CI
+make ci                       # Complete pipeline
+```
+
+## 📝 Code Style
+
+### Required Patterns
+
+**1. Strict Types (Always First)**
+```php
+<?php
+
+declare(strict_types=1);
+```
+
+**2. File Header (Auto-managed by PHP-CS-Fixer)**
+```php
+/**
+ * This file is part of the package netresearch/rte-ckeditor-image.
+ *
+ * For the full copyright and license information, please read the
+ * LICENSE file that was distributed with this source code.
+ */
+```
+
+**3. Import Order**
+- Classes first
+- Functions second
+- Constants third
+- One blank line before namespace
+
+**4. Type Hints**
+- All parameters must have type hints
+- All return types must be declared
+- Use nullable types `?Type` when appropriate
+- Use union types `Type1|Type2` for PHP 8+
+
+**5. Property Types**
+```php
+private ResourceFactory $resourceFactory;        // Required type declaration
+private readonly ResourceFactory $factory;       // Readonly for immutability
+```
+
+**6. Alignment**
+```php
+$config = [
+    'short'  => 'value',       // Align on =>
+    'longer' => 'another',
+];
+```
+
+## 🔒 Security
+
+### FAL (File Abstraction Layer)
+- **Always use FAL:** Never direct file system access
+- **ResourceFactory:** For retrieving files by UID
+- **File validation:** Check isDeleted(), isMissing()
+- **ProcessedFile:** Use process() for image manipulation
+
+```php
+// ✅ Good: FAL usage
+$file = $this->resourceFactory->getFileObject($id);
+if ($file->isDeleted() || $file->isMissing()) {
+    throw new \Exception('File not found');
+}
+
+// ❌ Bad: Direct file access
+$file = file_get_contents('/var/www/uploads/' . $filename);
+```
+
+### Input Validation
+- **Type cast superglobals:** `(int)($request->getQueryParams()['id'] ?? 0)`
+- **Validate before use:** Check ranges, formats, existence
+- **Exit on error:** Use HTTP status codes with `HttpUtility::HTTP_STATUS_*`
+
+### XSS Prevention
+- **Fluid templates:** Auto-escaping enabled by default
+- **JSON responses:** Use `JsonResponse` class
+- **Localization:** Via `LocalizationUtility::translate()`
+
+## ✅ PR/Commit Checklist
+
+### PHP-Specific Checks
+1. ✅ **Strict types:** `declare(strict_types=1);` in all files
+2. ✅ **Type hints:** All parameters and return types declared
+3. ✅ **PHPStan:** Zero errors (`composer ci:test:php:phpstan`)
+4. ✅ **Code style:** PSR-12/PER-CS2.0 compliant (`make format`)
+5. ✅ **Rector:** No modernization suggestions (`composer ci:test:php:rector`)
+6. ✅ **FAL usage:** No direct file system access
+7. ✅ **DI pattern:** Constructor injection, no `new ClassName()`
+8. ✅ **PSR-7:** Request/Response for controllers
+9. ✅ **Documentation:** PHPDoc for public methods
+
+## 🎓 Good vs Bad Examples
+
+### ✅ Good: Controller Pattern
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace Netresearch\RteCKEditorImage\Controller;
+
+use Psr\Http\Message\ResponseInterface;
+use Psr\Http\Message\ServerRequestInterface;
+use TYPO3\CMS\Core\Http\JsonResponse;
+use TYPO3\CMS\Core\Resource\ResourceFactory;
+
+final class SelectImageController
+{
+    public function __construct(
+        private readonly ResourceFactory $resourceFactory
+    ) {
+    }
+
+    public function infoAction(ServerRequestInterface $request): ResponseInterface
+    {
+        $fileUid = (int)($request->getQueryParams()['fileId'] ?? 0);
+
+        if ($fileUid <= 0) {
+            return new JsonResponse(['error' => 'Invalid file ID'], 400);
+        }
+
+        $file = $this->resourceFactory->getFileObject($fileUid);
+
+        return new JsonResponse([
+            'uid'    => $file->getUid(),
+            'width'  => $file->getProperty('width'),
+            'height' => $file->getProperty('height'),
+        ]);
+    }
+}
+```
+
+### ❌ Bad: Anti-patterns
+
+```php
+<?php
+// ❌ Missing strict types
+namespace Netresearch\RteCKEditorImage\Controller;
+
+// ❌ Missing PSR-7 types
+class SelectImageController
+{
+    // ❌ No constructor DI
+    public function infoAction($request)
+    {
+        // ❌ Direct superglobal access
+        $fileUid = $_GET['fileId'];
+
+        // ❌ No DI - manual instantiation
+        $factory = new ResourceFactory();
+
+        // ❌ No type safety, no validation
+        $file = $factory->getFileObject($fileUid);
+
+        // ❌ Manual JSON encoding
+        header('Content-Type: application/json');
+        echo json_encode(['uid' => $file->getUid()]);
+        exit;
+    }
+}
+```
+
+### ✅ Good: EventListener Pattern
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace Netresearch\RteCKEditorImage\EventListener;
+
+use TYPO3\CMS\Backend\Routing\UriBuilder;
+use TYPO3\CMS\RteCKEditor\Form\Element\Event\AfterPrepareConfigurationForEditorEvent;
+
+final class RteConfigurationListener
+{
+    public function __construct(
+        private readonly UriBuilder $uriBuilder
+    ) {
+    }
+
+    public function __invoke(AfterPrepareConfigurationForEditorEvent $event): void
+    {
+        $configuration = $event->getConfiguration();
+        $configuration['style']['typo3image'] = [
+            'routeUrl' => (string)$this->uriBuilder->buildUriFromRoute('rteckeditorimage_wizard_select_image'),
+        ];
+        $event->setConfiguration($configuration);
+    }
+}
+```
+
+### ❌ Bad: EventListener Anti-pattern
+
+```php
+<?php
+namespace Netresearch\RteCKEditorImage\EventListener;
+
+class RteConfigurationListener
+{
+    // ❌ Wrong signature - not invokable
+    public function handle($event)
+    {
+        // ❌ Manual instantiation instead of DI
+        $uriBuilder = \TYPO3\CMS\Core\Utility\GeneralUtility::makeInstance(UriBuilder::class);
+
+        // ❌ Array access without type safety
+        $config = $event->getConfiguration();
+        $config['style']['typo3image']['routeUrl'] = $uriBuilder->buildUriFromRoute('rteckeditorimage_wizard_select_image');
+        $event->setConfiguration($config);
+    }
+}
+```
+
+### ✅ Good: FAL Usage
+
+```php
+protected function getImage(int $id): File
+{
+    try {
+        $file = $this->resourceFactory->getFileObject($id);
+
+        if ($file->isDeleted() || $file->isMissing()) {
+            throw new FileNotFoundException('File not found or deleted', 1234567890);
+        }
+    } catch (\Exception $e) {
+        throw new FileNotFoundException('Could not load file', 1234567891, $e);
+    }
+
+    return $file;
+}
+```
+
+### ❌ Bad: Direct File Access
+
+```php
+// ❌ Multiple issues
+protected function getImage($id)  // Missing return type, no type hint
+{
+    // ❌ Direct file system access, bypassing FAL
+    $path = '/var/www/html/fileadmin/' . $id;
+
+    // ❌ No validation, no error handling
+    if (file_exists($path)) {
+        return file_get_contents($path);
+    }
+
+    return null;  // ❌ Should throw exception or return typed null
+}
+```
+
+## 🆘 When Stuck
+
+### Documentation
+- **API Reference:** [docs/API/Controllers.md](../docs/API/Controllers.md) - Controller APIs
+- **Event Listeners:** [docs/API/EventListeners.md](../docs/API/EventListeners.md) - PSR-14 events
+- **Data Handling:** [docs/API/DataHandling.md](../docs/API/DataHandling.md) - Database hooks
+- **Architecture:** [docs/Architecture/Overview.md](../docs/Architecture/Overview.md) - System design
+
+### TYPO3 Resources
+- **FAL Documentation:** https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ApiOverview/Fal/Index.html
+- **PSR-14 Events:** https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ApiOverview/Events/Index.html
+- **Dependency Injection:** https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ApiOverview/DependencyInjection/Index.html
+- **Controllers:** https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ApiOverview/Backend/Controllers/Index.html
+
+### Common Issues
+- **ResourceFactory errors:** Check file exists, not deleted, proper UID
+- **DI not working:** Verify `Configuration/Services.yaml` registration
+- **PHPStan errors:** Update baseline: `composer ci:test:php:phpstan:baseline`
+- **Type errors:** Enable strict_types, add all type hints
+
+## 📐 House Rules
+
+### Controllers
+- **Extend framework controllers:** ElementBrowserController for browsers
+- **Final by default:** Use `final class` unless inheritance required
+- **PSR-7 types:** ServerRequestInterface → ResponseInterface
+- **JSON responses:** Use `JsonResponse` class
+- **Validation first:** Validate all input parameters at method start
+
+### EventListeners
+- **Invokable:** Use `__invoke()` method signature
+- **Event type hints:** Type-hint specific event classes
+- **Immutability aware:** Get, modify, set configuration/state
+- **Final classes:** Event listeners should be final
+
+### DataHandling
+- **Soft references:** Implement soft reference parsing for data integrity
+- **Database hooks:** Use for maintaining referential integrity
+- **Transaction safety:** Consider rollback scenarios
+
+### Dependencies
+- **Constructor injection:** All dependencies via constructor
+- **Readonly properties:** Use `readonly` for immutable dependencies
+- **Interface over implementation:** Depend on interfaces when available
+- **GeneralUtility::makeInstance:** Only for factories or when DI unavailable
+
+### Error Handling
+- **Type-specific exceptions:** Use TYPO3 exception hierarchy
+- **HTTP status codes:** Via HttpUtility constants
+- **Meaningful messages:** Include context in exception messages
+- **Log important errors:** Use TYPO3 logging framework
+
+### Testing
+- **Functional tests:** For controllers, database operations
+- **Unit tests:** For utilities, isolated logic
+- **Mock FAL:** Use TYPO3 testing framework FAL mocks
+- **Test location:** `Tests/Functional/` and `Tests/Unit/`
+
+## 🔗 Related
+
+- **[Resources/AGENTS.md](../Resources/AGENTS.md)** - JavaScript/CKEditor integration
+- **[Tests/AGENTS.md](../Tests/AGENTS.md)** - Testing patterns
+- **[Configuration/Services.yaml](../Configuration/Services.yaml)** - DI container configuration
+- **[docs/API/](../docs/API/)** - Complete API documentation

package/skills/repo-bootstrap/references/examples/t3x-rte-ckeditor-image/composer.json

@@ -0,0 +1,8 @@
+{
+    "name": "example/t3x-rte-ckeditor-image",
+    "type": "typo3-cms-extension",
+    "require": {
+        "php": "^8.1",
+        "typo3/cms-core": "^12.4 || ^13.4"
+    }
+}

package/skills/repo-bootstrap/references/feedback-memory-schema.md

@@ -0,0 +1,135 @@
+# Feedback Memory Schema
+
+Canonical format for **approved session learnings** materialized as project-rule or user-memory files. This schema is the contract between `retro-skill` (which writes these files) and `agent-rules-skill` (which manages how they integrate with AGENTS.md and project documentation).
+
+## When this schema applies
+
+| Destination | Path |
+|---|---|
+| **user-memory** (personal preference across projects) | `~/.claude/projects/<project-dir-slug>/memory/feedback_<slug>.md` |
+| **project-rule** (project-specific convention) | `<project>/docs/feedback/feedback_<slug>.md` |
+
+### Variable definitions
+
+| Variable | Meaning | Example |
+|---|---|---|
+| `<project-dir-slug>` | Claude Code's encoding of the absolute working directory for user-memory. Slashes are replaced with `-`. | `/home/sme/p` → `-home-sme-p` |
+| `<slug>` | kebab-case filename slug for *this specific learning* | `merge-strategy`, `preserve-commit-signing` |
+
+`<project-dir-slug>` and `<slug>` are distinct. `retro-skill` MUST compute `<project-dir-slug>` deterministically from the absolute working directory at the time of materialization (not from any frontmatter field).
+
+For user-memory **global** scope (not tied to a single project): place under whatever project-dir-slug Claude Code uses for global memory; consult `~/.claude/projects/` for the convention in use.
+
+## Schema
+
+```markdown
+---
+name: <human-readable title; may be free prose>
+description: "<one-line summary; used for relevance scoring across sessions>"
+type: feedback
+originSessionId: <session-id-from-jsonl-filename>
+---
+**Why:** <1-2 paragraphs explaining the friction and root cause>
+
+**How to apply:** <1-2 paragraphs describing how the assistant should behave next time>
+```
+
+### Field semantics
+
+| Field | Required | Notes |
+|---|---|---|
+| `name` | yes | Human-readable title for the learning. May be a free-form sentence (e.g. `"Preserve commit signing on rewrite operations"`) or a short slug (e.g. `"merge strategy"`). **Not necessarily kebab-case** — the canonical examples use both natural language and slugs. The **filename** uses an independent kebab-case slug (see "Filename slug" below). |
+| `description` | yes | One-line summary, ≤200 chars. Used by retro-skill to score relevance against new friction. **MUST be double-quoted** when it contains any of `: # [ ] { } , & * ! \| > ' " % @` or a leading whitespace, or it may break YAML parsing. Safer rule: quote unconditionally. |
+| `type` | yes | always `feedback` (distinguishes from other memory types). |
+| `originSessionId` | recommended, not required | Session ID where the friction was first observed (audit trail). If absent, the file is still valid but loses traceability. |
+| `**Why:**` body section | yes | Start of line, exact form `**Why:** ` (with trailing space). Without this, the file rots — readers can't judge if it still applies. |
+| `**How to apply:**` body section | yes | Start of line, exact form `**How to apply:** `. Vague rules don't change behavior. |
+
+### Filename slug (independent from `name`)
+
+The `<slug>` in the filename `feedback_<slug>.md` is **separately chosen** by retro-skill, kebab-case, descriptive of the learning topic. It is NOT required to match `frontmatter.name`.
+
+Canonical examples demonstrate the freedom: file `feedback_skill-sources.md` has `name: "skill source vs cache"`; file `feedback_no-version-bumps-in-feature-prs.md` has `name: "No version bumps in feature PRs"`.
+
+## Project-rule placement
+
+When `retro-skill` materializes a `project-rule` destination:
+
+1. **Write file:** `<project>/docs/feedback/feedback_<slug>.md` (create `docs/feedback/` if missing).
+2. **Add AGENTS.md index entry** under a `## Approved learnings` section:
+
+```markdown
+## Approved learnings
+
+- [feedback_<slug>.md](docs/feedback/feedback_<slug>.md) — <one-line summary from frontmatter description>
+```
+
+The index entry is a single line; the full prose lives in the linked file.
+
+### Section position in AGENTS.md
+
+`## Approved learnings` should be placed **after `## Key Decisions` and before `## Boundaries`** in the `root-thin.md` template's section order. **Place it outside `<!-- AGENTS-GENERATED:START ... -->` markers** so `generate-agents.sh --update` preserves it — this section is managed by retro-skill, not by the generator.
+
+If the project's AGENTS.md is at or near the 150-line cap (the harness AH-02 threshold), prune older inactive learnings or move to a scoped `AGENTS.md` rather than letting the index grow unbounded.
+
+## User-memory placement
+
+When `retro-skill` materializes a `user-memory` destination:
+
+1. **Compute path:** `~/.claude/projects/<project-dir-slug>/memory/feedback_<slug>.md` for project-scoped learnings, OR the global-scope path (consult `~/.claude/projects/`).
+2. **Write file** using the schema above.
+3. **Add MEMORY.md index entry** under the existing flat `## Topic Files` section (no sub-sections):
+
+```markdown
+- [feedback_<slug>.md](feedback_<slug>.md) — <one-line summary>
+```
+
+Do not create a separate `## Feedback` heading — MEMORY.md uses a single flat list.
+
+## Why this schema (rationale)
+
+- **Frontmatter** is machine-readable and tool-discoverable.
+- **`description`** lets retro-skill detect duplicates and rank relevance.
+- **`Why:` + `How to apply:`** structure forces meaningful content; vague file = vague rule.
+- **`originSessionId`** allows tracing back to the friction; supports audit and deprecation.
+
+## Validation
+
+A valid feedback file has:
+
+- YAML frontmatter present and parseable by PyYAML / yq.
+- Required fields populated (non-empty): `name`, `description`, `type`.
+- `description` is double-quoted (or doesn't contain YAML-special characters).
+- Both `**Why:** ` and `**How to apply:** ` body markers present at start-of-line.
+- File path matches `feedback_<slug>.md` where `<slug>` is kebab-case (independent of frontmatter `name`).
+
+`originSessionId` is recommended but its absence does NOT invalidate the file.
+
+Optional `scripts/verify-feedback-memory.sh` (not yet implemented; tracked as TODO) can enforce this in CI.
+
+## Validation gap (current state)
+
+`references/verification-guide.md` does **not** yet include a row for feedback files. Adding the check is tracked separately. retro-skill's PR-time validation of materialized files is the de-facto enforcement until the agent-rules-skill validator catches up.
+
+## Examples in the wild
+
+The user's own memory at `~/.claude/projects/-home-sme-p/memory/` contains **9 files** following this schema:
+
+- `feedback_dup-repo-verification.md`
+- `feedback_merge-strategy.md`
+- `feedback_merge-vs-rollout.md`
+- `feedback_no-version-bumps-in-feature-prs.md`
+- `feedback_obsolete-docs-prefer-delete.md`
+- `feedback_preserve-commit-signing.md`
+- `feedback_skill-iteration-cadence.md`
+- `feedback_skill-sources.md`
+- `feedback_subagent-default.md`
+
+Some include an extended `metadata:` block (e.g. `feedback_merge-vs-rollout.md` has `metadata: { node_type: memory, type: feedback }`); that variant is tolerated, not required.
+
+## See also
+
+- `retro-skill/references/destination-taxonomy.md` — Where this schema applies (in retro-skill repo)
+- `retro-skill/references/patch-workflow.md` — How retro-skill writes these (in retro-skill repo)
+- `references/output-structure.md` — How AGENTS.md indexes feedback files
+- `references/verification-guide.md` — How to validate the resulting AGENTS.md

package/skills/repo-bootstrap/references/git-hooks-setup.md

@@ -0,0 +1,79 @@
+# Git Hooks Setup for Autonomous Agents
+
+## Why Hooks Matter
+
+Git hooks catch formatting errors, lint violations, and test failures **before commit** -- not minutes later in CI. For autonomous agents, this is critical: a failed CI run wastes time, tokens, and creates noisy fix-up commits. Hooks provide immediate feedback in the local loop.
+
+## Detecting the Hook Framework
+
+Check for these files in the repository root:
+
+| File | Framework | Language ecosystem |
+|------|-----------|-------------------|
+| `lefthook.yml` or `.lefthook.yml` | [Lefthook](https://github.com/evilmartians/lefthook) | Any (Go binary) |
+| `captainhook.json` | [CaptainHook](https://github.com/captainhookphp/captainhook) | PHP / Composer |
+| `.husky/` directory | [Husky](https://github.com/typicode/husky) | Node.js / npm |
+| `.pre-commit-config.yaml` | [pre-commit](https://pre-commit.com/) | Python / Any |
+
+## Setup Commands
+
+### Lefthook
+
+```bash
+# If a Makefile target exists (preferred)
+make setup
+
+# Otherwise install directly
+go install github.com/evilmartians/lefthook@latest
+lefthook install
+```
+
+### CaptainHook (PHP)
+
+```bash
+# Hooks install automatically via Composer plugin
+composer install
+```
+
+CaptainHook registers itself as a Composer plugin. Running `composer install` triggers the post-install hook that sets up git hooks. No extra step needed.
+
+### Husky (Node.js)
+
+```bash
+# Hooks install automatically via npm prepare script
+npm install
+```
+
+Husky uses the `prepare` lifecycle script in `package.json`. Running `npm install` (or `yarn install`) automatically runs `husky install`.
+
+### pre-commit (Python)
+
+```bash
+pip install pre-commit
+pre-commit install
+```
+
+Or if the project uses a virtual environment:
+
+```bash
+# Inside activated venv
+pre-commit install
+```
+
+## When No Hooks Exist
+
+If no hook framework is detected:
+
+1. **Do not skip this step.** The absence of hooks is a gap worth flagging.
+2. Suggest adding hooks to the project -- recommend Lefthook for polyglot repos, or the ecosystem-native tool (Husky for JS, CaptainHook for PHP, pre-commit for Python).
+3. See the `git-workflow` skill for hook framework setup guidance.
+
+## Never Skip Hooks
+
+**NEVER** use `--no-verify` to bypass hooks. If a hook fails:
+
+1. Read the hook output to understand the failure.
+2. Fix the underlying issue (formatting, lint error, failing test).
+3. Stage the fix and commit again.
+
+Skipping hooks defeats their purpose and pushes problems to CI where they are more expensive to fix.