Pipeline Optimizer

English — Official English version of pipeline-optimizer.

Pipeline Optimizer / Project-Folder Optimizer (English)

6-step renovation without incompatibilities — applicable at two scales:

A pipeline here means a topic-oriented top-level structure in which multiple projects live under shared conventions (e.g. a software pipeline with release rules, a research pipeline with a publication procedure).

Both use the same 6-step workflow — the only difference is the scope (pipeline-wide vs. single project) and, accordingly, the depth of the building-stock survey in step A.

When this skill applies

The skill applies as soon as you are asked to improve, rebuild, or extend an existing structure — not for greenfield construction. Concrete triggers:

Pipeline level (scope: whole pipeline):

• "Make pipeline X better"
• "Optimize the stack"
• "Renovate the software pipeline"
• "Documentation consolidation in the research pipeline"
• Substantial intervention in a topic pipeline, central _tools/, or system components

Project-folder level (scope: single project folder):

• "Clean up / optimize project folder X"
• "Improve the folder structure in Y"
• "Refactor a single tool"
• "Unify a paper-project setup"
• "Align a game project folder with the pipeline standard"

Cross-cutting:

• "Rebuild X / integrate it into existing Y"
• "Refactoring", "consolidation"
• "Unify conventions"
• "Integrate into an existing system"

The building-stock metaphor

Renovating a house first requires knowing what it is made of (stone, wood, plastic), what it is for (mountain hut, software forge), and where it already fulfills functions. The same discipline applies to pipelines.

Procedure — 6 steps (do NOT skip, do NOT reorder)

Step A — Survey the building stock

Question: What is the house made of?

Pipeline scope (all root docs + tools + templates):

• Read all root documents completely (not just snippets/insertion points)
• Go through template folders (_templates/, _TEMPLATES/) and tool folders (_tools/)
• Policy files: e.g. GITHUB-POLICY.md, RELEASE-MANAGEMENT.md, QUALITY_RULES.md, NAMING-SYSTEM.md, publication procedures, …
• Status snapshots: e.g. PROJECT_STATUS.md, status overviews, releases.json, registry files
• Checklists: e.g. release checklists, build/PDF checklists
• Workflows: AGENTS.md, GUIDE.md, SKILL.md
• Lessons-learned files: LESSONS_LEARNED.md, MEMORY.md, loop-state files

Project-folder scope (single-project substance + relevant pipeline conventions):

• Read all markdown and control files in the project folder (README, CHANGELOG, TASKS/TODO, DONE, CONCEPT, action plan, proof notes, …)
• Survey the code structure: src/, tests/, build configuration (pyproject.toml, requirements.txt, project manifests, toolchain files, …)
• Take the parent pipeline's conventions into account (e.g. for a software project: GitHub policy, naming system, release management, templates)
• Scan existing tools/scripts in the project (_tools/, _scripts/, build_*.bat, START scripts)
• Configuration files: .gitignore, LICENSE, NOTICE, SECURITY.md, CODE_OF_CONDUCT.md

Anti-pattern: Using grep -l "<keyword>" to find insertion points and inserting there without knowing the file's context.

Output: Inventory note with all relevant conventions, tools, and templates at the chosen scope.

Step B — Identify the purpose

Question: What does the house exist for?

State the purpose explicitly in 1-2 sentences.

Pipeline examples:

Project-folder examples:

The purpose steers every intervention — measures that do not serve the purpose are dropped.

Step C — Sketch the ideal picture

Question: What would a perfect house for this purpose look like?

• Sketch it from your own perspective (short, max. 10 points)
• Bring in a best-practice comparison (e.g. Vercel stack for SaaS, scientific-python stack for research)
• Do not descend into detail optimization — a top-level sketch is enough

Output: 5-10 points "ideal state per pipeline"

Step D — Gap analysis + plan

Four questions per pipeline:

1. What does the house already have? — Even if solved differently from the ideal but functionally equivalent. Example: The ideal says "pip-licenses for third-party licenses". Reality: a custom generator script wraps it → functionally equivalent, no intervention needed.

2. What impedes the function? — Existing structures that cause breaks or extra effort today.

3. What is non-functional? — Dead code, outdated conventions, unused tools.

4. What would measurably improve functions? — Concrete interventions with expected benefit.

→ From this, a concrete plan:

• What gets newly built?
• What gets extended?
• What gets demolished?
• What stays unchanged (important to name!)

Output: Plan table with columns Intervention / Existing / Measure / Rationale

Step E — Work empirically

Do not only plan top-down — collect pain points:

• Known bugs: issue tracker, TASKS/TODO/DONE files
• Error history: lessons-learned files, bugfix logs, check registries
• Automation breaks: "What do I always have to do manually?"
• User interview: ask specifically — pain points, wishes, workarounds
• Self-test: walk through the pipeline (create a new project, run a build, simulate a release) — where does it break?

The empirically found pain points prioritize the plan from step D.

Step F — Retests after implementation

• Commission fresh subagents (unburdened by the renovation context) to walk through the changed workflow
• Measurable before/after values: setup time, error rate, number of manual steps, build time
• Anti-regression check: do existing workflows still work after the change?
• If there is no measurable improvement or a regression: roll back the renovation or readjust

Anti-patterns (forbidden)

Case study — the NOTICE.md incident

Assignment: Implement pipeline improvements across several topic pipelines (software, research, games).

Mistake: Step A skipped — only insertion points searched instead of reading the full policy files.

Consequence: NOTICE.md introduced as a "new license file" in 7 files, although THIRD_PARTY_LICENSES.txt + a custom license generator (wrapper around pip-licenses) were already established — documented in the pipeline's GitHub policy (mandatory files + license checklist). All software projects already had THIRD_PARTY files.

Detection: Only after the user asked ("I'm fairly sure we already had rights management").

Correction: NOTICE.md removed from the project template, 6 further files adjusted, the existing license generator referenced instead of pip-licenses.

Lesson: Had step A been executed in full, the conflict would have been detected before writing.

Rules of thumb

1. For "improve the pipeline", first read as long as you write.
2. No new standard without proof that no existing one exists.
3. Use existing tools/wrappers instead of new parallel ones.
4. "More of the same" is usually worse than "extend what exists".
5. Rolling back on conflict is always better than running two parallel standards.

Completion checklist

Before reporting a pipeline renovation as "done":

• Step A: all relevant root docs read?
• Step B: pipeline purpose stated in 1-2 sentences?
• Step C: ideal picture sketched (5-10 points)?
• Step D: gap analysis with table (what stays / what is extended / what is new / what goes)?
• Step E: empirics checked (bugs, lessons, self-test, user interview)?
• Plan agreed with the user?
• Step F: tested with a fresh subagent — improvement measurable?
• No parallel standards introduced?
• On conflicts: rolled back or honestly accounted for?

Optimal project-folder structure (for the project-folder optimizer)

When the skill is applied to a single project folder, the following combined recommendation helps as an ideal reference (step C):

Anthropic standard (Claude Code)

Your own project-docs template (recommended)

If you maintain your own project documentation template (e.g. under <your-workspace>/_templates/project-docs/), three build-out profiles pay off. Example split: MINIMAL provides the session core set with 7 root files (AGENTS.md, CLAUDE.md, README.md, START.md, STATE.md, TODO.md, DONE.md) plus _tools/. STANDARD adds CHANGELOG.md, DECISIONS.md, and PATTERNS.md. FULL expands to 14 root files and additionally adds ARCHITECTURE.md, WORKFLOWS.md, TOOLS.md, GLOSSARY.md as well as workflows/ and .github/.

→ Use such a template as the base for new projects (copy instead of creating manually).

Pipeline-specific additions (examples)

Depending on the pipeline, further mandatory files come on top — typical patterns:

• Software project: LICENSE, CODE_OF_CONDUCT.md, SECURITY.md, CONTRIBUTING.md, THIRD_PARTY_LICENSES.txt (generated), pyproject.toml/requirements.txt, entry in the pipeline's central release registry. → If available: use the pipeline's cookiecutter template.
• Research project: concept document, action plan, publication plan, archive/source/result/data folders (_archive/, _sources/, _results/, _data/), paper/ for LaTeX. For proof projects: a proof-note file with the proof chain and status.
• Game project: project manifest and toolchain files of the engine (e.g. for Roblox/Rojo: default.project.json, rokit.toml, wally.toml, selene.toml), game design document, src/{server,client,shared}/ per engine convention.

Full detail reference

→ See references/optimal-project-structure.md in this skill folder (German). Contains:

• Example settings.json (Anthropic schema)
• Mandatory .gitignore entries
• Anti-patterns (what does NOT belong in project folders)
• Recommended workflows per pipeline type (software/research/game)
• YAML header convention for documentation files
• Auto-check sketch

Related skills (when to use instead of this one?)

The pipeline optimizer is responsible for renovation, not new construction or adoption. If your skill collection has a skill index, search it for matching bootstrapping skills.

Cross-references

• Detail reference: references/optimal-project-structure.md (in this skill folder)
• Anthropic Claude Code docs: https://docs.claude.com/en/docs/claude-code
• If available: global user rules (e.g. a "renovations" section in your ~/CLAUDE.md) and pipeline-specific stack descriptions

Scope choice: pipeline vs. project folder

If it is unclear which scope is meant, clarify before step A:

At project-folder scope, additionally always briefly check the parent pipeline's conventions (step A extended) so the intervention stays compatible with the pipeline.

Changelog

1.2.0 (2026-06-13)

• First publication in the skill library: personal paths, concrete pipeline/project names, and references to private skills replaced with generic examples; the procedure itself (6 steps, anti-patterns, case study, checklists) unchanged

1.1.1 (2026-06-01) and earlier

• Internal versions (private skill directory, before publication)