Imported from phomo17/claude-typo3-setup (.claude/skills/typo3-extension-concept-planning/SKILL.md). Install upstream with npx skills add phomo17/claude-typo3-setup --skill typo3-extension-concept-planning. Copyright stays with the author.

name: typo3-extension-concept-planning description: Methodology for planning a brand-new custom TYPO3 extension from a raw idea to a locked CONCEPT.md — covers the mandatory multi-source, multi-language prior-art research protocol, the RESEARCH.md finding log and its categories, the ambiguity sweep, the CONCEPT.md format (phases, exit criteria, non-goals), and the downstream multi-agent development workflow (research → structure → code plan → implement → review, per phase). ALWAYS load this skill when planning, scoping, or writing the initial concept for a new custom TYPO3 extension idea — before any structure or code planning starts. This is the methodology behind the typo3-concept-planner agent; load it whenever that agent runs, and also when reviewing or improving this workflow itself. Triggers (DE): neue TYPO3-Extension planen, Extension-Konzept, Idee für Erweiterung, CONCEPT.md erstellen, Recherche vor Extension-Entwicklung, Extension-Idee prüfen.

TYPO3 Extension Concept Planning

Skill: typo3-extension-concept-planning

Turns a raw extension idea into a locked, self-contained CONCEPT.md — and defines the phased build workflow that follows it. Written for the typo3-concept-planner agent. Company: Extension14v.

Core principle, ranked above everything else in this skill: a wrong or duplicate extension is worse than a slow one. Every step below exists because a real planning session skipped it once and produced a concept for an extension that already existed — twice, for the same idea.

0. Rejected-Ideas Check (do this first, before any research)

Before researching a new idea, check whether ~/.claude/rejected-ideas/ exists. If it does, look inside it for a file matching or closely related to the idea (<extension-name>-REJECTED.md). If a plausible match exists, read it and tell the user what was found and why it was rejected before doing anything else — do not silently re-research an idea that was already rejected. If the directory does not exist yet, say so honestly ("no rejected-ideas archive yet") rather than reporting as if a search had come up empty.

1. Research Protocol

Research has exactly two mandatory deep passes, plus ad-hoc dispatches in between:

1. Opening pass — right after the raw idea is stated, before any spec questions. Broad, exploratory.
2. Closing pass — right when the concept is otherwise finished and CONCEPT.md is about to be written. This pass must be more targeted than the opening one: by now the concept has specific terminology, mechanisms and a settled feature set that the opening pass never had, so search with those specific terms, not just the original pitch framing. The closing pass also checks the planned extension name and key against TER, Packagist and GitHub for collisions.

Both passes are dispatched to typo3-researcher (never done inline by the concept-planner itself). Report results to the user in chat, in German. Never write research results into CONCEPT.md — that clutters it. They go into RESEARCH.md (see §2) and into the chat.

Fixed source catalog (every pass)

• TYPO3 official docs full-text search (docs.typo3.org)
• TER (extensions.typo3.org)
• GitHub search — broader than the official typo3 org
• Known TYPO3 agency/vendor sites, checked explicitly by name: in2code, xima (media), b13, waldhacker, punkt.de, and any other major TYPO3 Solution Partner relevant to the topic — commercial products rarely surface through TER/forum search alone
• TYPO3 community forums (typo3.net, TYPO3 Talk/Slack archives where searchable)

Free search (every pass)

Google, DuckDuckGo, Brave, Startpage.

Multi-framing, multi-language (every pass)

Search the underlying problem, not just the extension's working title — a real solution can be branded completely differently (e.g. a "review reminder" idea can exist under the name "content planner" with no date/reminder language anywhere in its own description). Use several independent keyword framings per idea, each run in German, English, French, and Spanish.

Classifying findings

Every finding gets two independent tags:

Relevance: helpful / might be helpful / not helpful

Type:

Finding age (for anything claiming or implying non-existence — forum answers, "no extension for this" comments, etc.):

A "direct overlap / existing solution" finding that is actively maintained is the strongest possible signal to stop and consult the user before continuing.

2. RESEARCH.md

Sits next to CONCEPT.md. Never delete an entry — if a finding turns out to be less/more relevant than first thought, move it to the correct relevance category instead. The file must always show everything that was ever actually checked.

Entry format: URL — one-line description of what's at that URL — timestamp — relevance tag — type tag.

Lifecycle:

• During planning: typo3-concept-planner may create and freely edit it.
• Once development starts: read-only for reference ("what did we already check"), with one exception — if the researcher is dispatched again mid-build and turns up a hard blocker, add that single finding under a During Development category. No other edits during the build.

3. Spec Clarification & Ambiguity Sweep

Clarify open questions with the user interactively (grouped, short-answer-friendly, same pattern as a normal planning chat). Before writing CONCEPT.md, run an explicit ambiguity sweep: go through the drafted concept and list every point where a decision was assumed rather than explicitly stated by the user. Confirm each one individually — don't let silent assumptions ride into the locked file.

4. CONCEPT.md

Written in English. Created only on the user's explicit instruction, only once planning (research + spec + ambiguity sweep) is fully done.

Must be fully self-contained. typo3-ext-planner and typo3-code-planner only ever see this file, never the planning chat. Nothing may be implied or assumed from conversation context.

Required sections:

1. What the extension is, who it's for, why it's needed
2. How it intends to solve that (behavior, not code/file structure)
3. Explicit non-goals — mandatory section, not optional
4. Compatibility: TYPO3 v13.4 through latest v14, one codebase; Composer and legacy, legacy as the default assumption, with any Composer-only mechanism explicitly called out and flagged for testing in a real Composer environment
5. Accessibility and GEO baked in as concept-level considerations (this agent loads typo3-geo-optimization and typo3-accessibility-planning itself, same as typo3-ext-planner/typo3-code-planner — so these shape feature decisions here, not just implementation later)
6. Development phases — the agent itself decides the breakdown once it has the full picture, aiming for phases large enough to be meaningful standalone milestones and few enough to stay manageable (no fixed number). For every phase, state explicitly:
   • which concept requirements/features belong to it (so typo3-ext-planner knows what to scope)
   • its exit criterion — a concrete, checkable statement of "done" for that phase
7. The token-efficiency principle (see §7 of this skill) in one short line, so it reaches the downstream agents too
8. Vendor/key: vendor is always Extension14v; the extension key follows the extension's own name

Locked after creation. Nobody edits it afterward — with exactly one exception: the user is asked explicitly, gives explicit permission for a specific change, and only then does the orchestrating typo3-concept-planner itself (not a dispatched typo3-implementer, to save tokens) make that one edit. No permission, no edit.

5. Development Phase Workflow (after CONCEPT.md is locked)

Default loop per phase — a template, adapted dynamically to what a given phase actually needs, not run mechanically:

Research (if needed) → typo3-ext-planner (structure) → typo3-code-planner (code plan) → typo3-implementer (implements) → typo3-reviewer (reviews) → typo3-implementer (fixes findings) → next phase.

The concept-planner does not dispatch this whole chain itself. For each phase it produces a ready-to-run dispatch roadmap (which agent, in what order, with what briefing) and hands that to the user, who triggers each step. The one exception is typo3-researcher: the concept-planner may dispatch it directly, since research is read-only and part of the concept-planner's own job. typo3-implementer is never dispatched automatically — it only ever runs on the user's explicit, separate go-ahead, in line with the project-wide rule that implementation requires explicit approval, never a default follow-on step after planning.

typo3-researcher can be re-dispatched ad hoc mid-phase whenever something needs checking.

Subagents never see the planning conversation, so every dispatch carries its own briefing: path to CONCEPT.md, current phase scope and exit criterion, target version range, Composer/legacy expectations.

Before the first phase starts, ask the user two questions (every run, fresh — no carried-over default):

1. Manual test phase between build phases?
   • Yes → at the end of each phase, produce a beginner-friendly, step-by-step test list in the chat. State which directory any terminal command runs from. For v14 installations, describe the new v14 backend layout (card-based Page module view) — never assume the older layout carried over from v13.
   • No → phases run back-to-back without pausing, until the user writes something like "pause at the next good point" in chat.
2. For ambiguities that come up during the build, should the user be asked, or should the agent decide autonomously?

Symmetric escalation rule — applies identically to both roles below: report to the user, never silently decide or silently ignore.

• typo3-researcher turns up a hard blocker: report immediately (main chat). During active development, do not halt the build for it — log it (RESEARCH.md, During Development) and keep going; the user evaluates and decides next steps. During planning (before CONCEPT.md exists), report it and wait — planning pauses until the user has looked at it.
• typo3-reviewer finds a contradiction with CONCEPT.md itself (not a code bug, but a requirement that turns out to be wrong/impossible): same treatment as a blocker finding above — report, don't self-resolve.

README.md is typo3-implementer's job: create or extend it after every phase the reviewer has passed, so it always reflects current state. The implementer doesn't load this skill, so the orchestrator must include this instruction in the dispatch briefing every time. CONCEPT.md itself is never touched for this.

6. Rejected Ideas

If research (opening or closing pass) shows the idea already exists in a way that removes its reason for being built, or the user otherwise decides not to proceed, no CONCEPT.md is written. Instead the concept-planner writes a short summary of the idea and the concrete reason it was rejected, including the finding that killed it, directly into the chat for the user. The concept-planner does not have write access to a ~/.claude/rejected-ideas/ archive and does not create one itself. Whether and how that summary gets saved for future reference (for example as a file the user creates themselves) is a separate decision the user makes and explicitly approves — it is not something this workflow does on its own. §0's check reads that archive only if and once it exists.

7. Token Efficiency

Correct planning and correct extension-building always outrank token cost — never cut research, spec clarity, or review quality to save tokens. Within that constraint, don't spend tokens that add no value to the extension (e.g. re-deriving something already settled, redundant re-reads, verbose restating). State this principle briefly in every CONCEPT.md so it reaches the downstream agents too.