# Cursor Playbook for Ordio Projects

**Last Updated:** 2026-04-04

**Official Cursor docs (rules, skills, subagents, MCP):** [`CURSOR_OFFICIAL_DOCS_REFERENCE.md`](CURSOR_OFFICIAL_DOCS_REFERENCE.md)

### Cursor product notes (2026, token- and speed-relevant)

- **Cursor 3** ([blog](https://cursor.com/blog/cursor-3)): agent-first UI, **parallel local/cloud agents**, handoff when a job is long-lived or you switch machines—can reduce “one giant chat” token piles. Try **Agents Window**: `Cmd+Shift+P` → *Agents Window* ([docs](https://cursor.com/docs/agent/agents-window)).
- **Composer 2** ([blog](https://cursor.com/blog/composer-2)): Cursor’s default coding model direction includes **better token efficiency**; keep choosing model tier by task ([`CURSOR_MODEL_CONFIGURATION.md`](CURSOR_MODEL_CONFIGURATION.md)).
- **Skills vs rules:** Skills fit **procedural / on-demand** workflows; rules stay **declarative** for file-scoped guardrails—matches our thin `.cursor/skills/` routers ([dynamic context](https://cursor.com/blog/dynamic-context-discovery)).
- **MCP:** Definitions are discovered and loaded **when needed** (see [changelog 2.4](https://cursor.com/changelog/2-4))—still prefer Ordio **scripts/`make`** when they already answer the question ([`mcp-usage.mdc`](../../.cursor/rules/mcp-usage.mdc)).
- **Browser:** Integrated agent browser for local sites ([docs](https://cursor.com/docs/agent/tools/browser)); often faster than external MCP browser loops for simple checks.
- **Marketplace:** Plugins can bundle MCPs, skills, subagents ([plugins docs](https://cursor.com/docs/plugins))—optional; team SSOT remains this repo’s `.cursor/` and `docs/ai/`.

## When to open this doc

- **Default:** Do **not** read this file end-to-end for every task. Start with [`agent-workflows.md`](agent-workflows.md) (Quick route) and attach only the files you will change.
- **Open relevant sections when:** you are onboarding new behaviour, debugging a Cursor/MCP workflow, writing prompts for a complex multi-page change, or aligning with Ordio review habits (du tone, schema, QA).
- **Prefer:** `@` references to specific playbook sections or to page guides (`docs/guides/...`) instead of pasting large excerpts into chat.
- **Deep links:** Content workflows → section **Content workflows (blog, templates, tools)** below; rule map → **Rulebook map**; validation → **Quality checks before handoff** and project Make targets.

## Why this guide exists

Cursor works best when we feed it precise instructions that reflect how Ordio builds, reviews, and ships every part of the site—from comparison pages to ShiftOps flows, product features, and gated assets. This playbook captures the habits that keep work fast, du tone consistent, and deployments safe across the entire project.

## Core workflow

1. Confirm the brief
   - Identify the page or workflow type (use the decision tree below) and note any non-standard modules.
   - Review the relevant references: `docs/guides/PAGE_TYPE_GUIDES.md`, page-specific guides (e.g. `docs/guides/comparison-pages/COMPARISON_PAGES_GUIDE.md`), ShiftOps docs, and active user memories (du tone, Ordio mention once, no competitor praise).
   - Capture the goal, success criteria, dependencies, and deliverables in your own words before prompting the agent.
2. Provide scoped context to Cursor
   - Use `@Files` / `@Code` references instead of pasting large files.
   - **Cheap reads first:** `grep` / ripgrep for symbols or paths, then open **only** the files you need—avoid loading whole directories or long guides unless the task is discovery.
   - Link the exact template or component file (comparison page, product page, ShiftOps script, etc.) and any shared includes you expect to touch.
   - Include snippets of the sections that must change; leave the rest implicit.
   - When relevant, mention MCP tools (e.g. "Use Fetch MCP to validate schema at [URL]", "Run Lighthouse audit on [URL]", "Use Web Search to research [topic]").
3. Plan before editing
   - Ask the agent for a concrete checklist covering copy, markup, logic, assets, schema, QA, and tests.
   - Insist on file paths, selector names, and validation steps; reject vague plans and reference the rule that should apply (`.cursor/rules/global.mdc` plus the page-type rule).
   - Record the agreed plan inside the task (plan tool or comment) before modifying files.

### Plan structure requirements

**Canonical** five-phase checklist for Cursor Plan Mode in this repo (other docs should point here instead of duplicating phase names):

Use this structure every time you run Plan Mode:

1. **Discovery**
   - Audit context, confirm briefs, identify missing inputs or references.
   - Call out research tasks (docs to read, data to pull) and add them as to-dos before any edits.
2. **Implementation**
   - Numbered steps with target files (`v2/pages/...`, `v2/js/...`), selectors/functions, and the tool to use (Multi-Edit, `apply_patch`, script).
   - Note dependencies („update data JSON before editing PHP“).
3. **Validation**
   - Tests to run: `make validate` (single command) or lint, local preview, schema check, performance spot-check, accessibility scan with tools/commands.
4. **Risks & Rollback**
   - List potential breaking areas, monitoring steps, and how to revert if the change fails.
5. **Handoff**
   - Summarise deliverables, docs to update, and next follow-up owner (Cursor vs. human).

Reject any plan that skips phases, omits to-dos, or flattens steps into vague sentences.

4. Execute with the right editing tool
   - Prefer Multi-Edit (or `apply_patch`) when adjusting repeated patterns (FAQ items, table rows, checklist bullets).
   - Use block replacements (`<<< >>>`) for entire sections when copy rewrites are large.
   - Reserve single-line inline edits for quick fixes; avoid “retrying” the same prompt repeatedly.
   - When adding new assets, script the change (`node scripts/generate_responsive_logos.js`) once rather than editing variants manually.
5. Verify immediately
   - Run lint or syntax checks relevant to touched files.
   - Load the page locally and inspect the sections that matter for that page type (see the checklist in `docs/guides/PAGE_TYPE_GUIDES.md`).
   - Compare rendered layout with reference pages or design specs; ensure shared utility classes and CSS modules remain unchanged.
6. Document the outcome
   - Summarise what changed, why, and how to validate. Suggest `make validate` or `make pre-deploy` for verification.
   - Mention Ordio’s advantage in the response while keeping tone direct and friendly.
   - Offer to export a summary or follow-up list if the user wants a handoff.

## Rulebook map

- `.cursor/rules/global.mdc` – attaches to every task; enforces plan quality, tone, and QA expectations.
- `.cursor/rules/*-pages.mdc` – page-type guardrails (product, industry, tools, templates, download, webinar, pillar, static, homepage).
- `.cursor/rules/shiftops-backend.mdc` & `.cursor/rules/shiftops-frontend-core.mdc` / `shiftops-frontend-qa.mdc` – ShiftOps API/analyzer, workflows, and QA.
- `.cursor/rules/base-components.mdc` – HIGH PROTECTION for shared includes (header, footer, forms).
- `.cursor/rules/api-endpoints-core.mdc` & `.cursor/rules/api-endpoints-security.mdc` – Non-ShiftOps lead capture, HubSpot, and file generators.
- `.cursor/rules/mcp-usage.mdc` – MCP tool governance: when to use each MCP, MCP vs direct API. See `docs/development/MCP_INTEGRATION.md`.
- `.cursorignore` – trims context (node_modules, vendor, WordPress core, caches) so plans stay focused.
- `docs/ai/CURSOR_MODEL_CONFIGURATION.md` – choose model by capability (premium reasoning vs fast model), not by hardcoded model names.
- `docs/guides/PAGE_TYPE_GUIDES.md` – quick reference checklists for each workflow.
- `docs/ai/rule-hierarchy.md` – decision tree and scope map for every rule.
- `docs/ai/CURSOR_RULES_MAINTENANCE.md` – complete guide for maintaining and updating rules.

## Content workflows (blog, templates, tools)

**Start here:** `docs/content/blog/CONTENT_SYSTEM_INDEX.md` maps every blog workflow, Make shortcuts, FAQ SSOT, data collection, and links to Cursor rules.

**Phase map for agents:** `docs/content/blog/BLOG_AGENT_PHASE_RUNBOOK.md` — scaffold → data → SERP → outline gate → draft → apply/validate (dependencies + commands).

**Blog lexikon/ratgeber: phased work (Cursor 3)** — avoids one overloaded chat ([Agents Window](https://cursor.com/docs/agent/agents-window), [Cursor 3 blog](https://cursor.com/blog/cursor-3)):

1. **Thread A — Data:** Scaffold + `run-new-post-pipeline.php` (use `--dry-run` first if needed). Delegate **long/noisy shell** to the **Bash** subagent ([subagents](https://cursor.com/docs/context/subagents)) so the parent summary stays small.
2. **Human or Thread B — Hard gate:** Live **SERP** review and `SERP_ANALYSIS.md` (browser). Do **not** synthesize the outline until this is done.
3. **Thread C — Outline + draft (new chat):** Merge outline scaffold, `make blog-outline-gate`, then section-by-section HTML in `content-draft.html` ([`CURSOR_TOKEN_EFFICIENCY.md`](CURSOR_TOKEN_EFFICIENCY.md): reset context between major phases).
4. **Thread D — Ship:** `make blog-apply-validate-strict` or `make blog-post-validate-strict` + FAQ pipeline if applicable (`docs/content/blog/BLOG_WORKFLOW_EFFICIENCY.md`).

**Improve existing live pages (SEO/AEO/GEO):** `docs/content/PAGE_IMPROVEMENT_DATA_PLAYBOOK.md` — mandatory **Phase 0** baseline (Google Search Console + GA4 where available, plus SISTRIX/research per surface) before rewriting outlines, meta, or body copy. **Execution checklist:** `docs/content/PAGE_IMPROVEMENT_ITERATION_CHECKLIST.md` (period compare, Firecrawl, per-surface scripts). Cursor rule: `.cursor/rules/page-improvement-data-baseline.mdc`.

**New public pages (non-blog):** `docs/content/WEBSITE_PAGE_PUBLICATION_INDEX.md` — OG image checklist (`docs/systems/og-images/NEW_PAGE_OG_AND_SOCIAL_CHECKLIST.md`), registry/specs/Gemini prompts, tool vs download carousels before FAQ, and copy-paste todos under `docs/content/_templates/`. Skill: `ordio-new-page-og-carousel`.

**404 / Insights routing and shared error layouts:** `docs/systems/error-pages/ERROR_PAGES.md` (`.htaccess`, `router.php`, `v2/pages/errors/`).

### Project Agent Skills (`.cursor/skills/`)

Cursor loads skills from `.cursor/skills/<name>/SKILL.md`. Invoke with **`/`** in Agent chat and search for the skill name, or let the agent attach when relevant.

| Skill | Purpose |
|-------|---------|
| `ordio-blog-content-router` | Classify task → correct doc + validation ladder (`make blog-post-validate` / `-strict` / `-faq`, `blog-apply-validate`). |
| `ordio-faq-workflow` | Cross-surface FAQs → `docs/content/FAQ_WEBSITE_STANDARD.md`, rework tree, `faq-cross-surface.mdc`, surface validators. |
| `ordio-blog-new-post-pipeline` | Post-scaffold data pipeline, outline gate, section briefs (`run-new-post-pipeline.php` parallel stage after SISTRIX; `/ordio-blog-new-post-pipeline` or `@` skill). |
| `ordio-template-content-workflow` | Template pages and template content pipeline (`/ordio-template-content-workflow`). |
| `ordio-tools-content-block` | Tools/rechner SEO content blocks (`/ordio-tools-content-block`). |
| `ordio-new-page-og-carousel` | New tool/template/download page: OG asset + registry + carousel placement (`/ordio-new-page-og-carousel`). |
| `ordio-feature-page-seo-workflow` | Product feature pages (10 Funktionen): research pipeline, synthesis, FAQ iteration — [`FEATURE_PAGES_CONTENT_INDEX.md`](../content/pages/product-pages/FEATURE_PAGES_CONTENT_INDEX.md) (`/ordio-feature-page-seo-workflow`). |

Skills are **thin routers**: they link to `.mdc` rules and docs—**do not** duplicate long rule text inside `SKILL.md`.

### Plan mode and subagents

- Use **Plan mode** for new posts, large improvements, or unfamiliar pipelines so discovery and file lists are explicit first.
- **Built-in subagents** (Cursor — see [Subagents](https://cursor.com/docs/context/subagents)): **Explore** for broad codebase search without flooding the main thread; **Bash** for long or noisy shell output in isolation; **Browser** for rendered page checks (built-in browser tool or MCP, per your setup).
- **Custom subagents:** None are checked into this repo. Add them in **Cursor Settings** only for high-repeat, high-noise workflows (e.g. wide exploration with a fixed summary format, or standardized validate-log triage). Document the trigger (“when the parent agent should delegate”) in the subagent prompt; prefer built-in Explore/Bash/Browser first.

### Quality bar

Skills and shortcuts must **route** to validators (e.g. `make blog-post-validate-strict` before publish when body/meta changed)—they must not encourage skipping gates to save time. See `docs/content/blog/BLOG_WORKFLOW_EFFICIENCY.md`.

## Prompt patterns that work

- Kickoff prompt (after auditing context):
  ```
  I’m updating `v2/pages/compare_timetac.php` for a new {competitor} comparison. Goals: refresh hero copy to du tone, update pricing table with the attached data, and regenerate schema. Plan concrete steps, list files you’ll touch, and call out verification (visual diff + schema test). Avoid touching shared CSS.
  ```
- Multi-edit request:
  ```
  Update the pricing table rows in `compare_{competitor}.php`. Replace the current three `<tr>` blocks with the JSON array below. Use Multi-Edit so only those rows change. Keep utility classes identical.
  ```
- Copy review:
  ```
  Rewrite the FAQ answers in `compare_{competitor}.php` to du tone, simple sentences, no competitor praise, and mention Ordio once across the section. Return a diff we can apply.
  ```
- MCP prompts:
  ```
  Run a Lighthouse audit on https://www.ordio.com/tools/minijob-rechner
  Use the Excel MCP to inspect the output of the template generator at v2/systems/excel-template-generator/output/schichtplan.xlsx
  Use Fetch MCP to validate schema at [URL]
  Use Web Search to research [topic], then Fetch URLs for content
  Use Serper MCP to search Google for [query] (real SERPs; uses credits)
  Use Firecrawl MCP to scrape/crawl/extract when Fetch insufficient (uses credits)
  ```

## Editing guardrails

- Never change shared includes (`../base/*.php`, `comparison-pages.css`) unless explicitly tasked.
- Preserve layout classes (`grid`, `md:grid-cols-2`, spacing utilities) and CTA component structure.
- Keep Ordio branding intact: no gradients, brand blues and neutrals only, avoid purple.
- Ensure every new or updated paragraph uses du-friendly language and stays concise.
- Re-run responsive logo script whenever new base images are added; do not edit generated variants manually.
- When updating schema JSON-LD, validate keys and URLs, then re-run `jsonlint` or browser console validation.
- **Blog post content:** Never edit `v2/data/blog/posts/**/*.json` directly. Use `update-post-content.php` to apply content changes. See [BLOG_CONTENT_EDIT_WORKFLOW.md](../content/blog/BLOG_CONTENT_EDIT_WORKFLOW.md).
- **Blog heading structure:** H3s case-by-case; H2+paragraphs valid. Prioritize natural flow over rigid structure. When H3s are used, optional intro paragraph between H2 and first H3 for smoother flow. Content-driven; avoid cheesy transitions. See [CONTENT_WRITING_GUIDELINES.md](../content/blog/CONTENT_WRITING_GUIDELINES.md).

## Quality checks before handoff

- Visual: hero logo aligned, CTA buttons styled, carousel renders, FAQ toggles.
- Content: competitor name consistent, copy answers “why Ordio” once, no forced mentions.
- Performance: preload tag present, `srcset` includes 160w/320w, widths + heights set.
- SEO: title/description include year, canonical & OG URLs match slug, schema updated.
- Accessibility: images have descriptive alt, headings follow hierarchy, interactive elements keyboard focusable.

## Rule Validation & Maintenance

### Validating Rules

Before committing and pushing changes to `.cursor/rules/`:

1. Run `make rules`: syncs `docs/ai/METADATA_INDEX.json` from `.mdc` files first, then validates metadata, globs (fast scan: skips `docs/backups`, `.cursor/projects`), rule links, and skill references.
2. Commit the updated `docs/ai/METADATA_INDEX.json` with your rule changes (CI will fail if the index is out of sync)

```bash
# Full pipeline (~seconds locally; use .venv/bin/python if system python lacks PyYAML)
make rules

# Or run individually (typical order):
bash scripts/maintain-rules.sh
python3 scripts/generate-rule-metadata.py   # Regenerate index from rule files
python3 scripts/validate-rules.py           # YAML + index consistency
python3 scripts/validate-rule-globs.py      # Glob patterns vs repo files
python3 scripts/validate-rule-links.py      # Cross-references in rules
```

### Testing Rule Discovery

Verify rules apply correctly to files:

```bash
# Test which rules apply to a specific file
python3 scripts/find-rules-for-file.py v2/pages/compare_planday.php
```

### Common Rule Issues

**Rule not applying:**

- Check glob patterns match file path
- Verify YAML frontmatter is valid
- Regenerate `docs/ai/METADATA_INDEX.json`

**Glob pattern not matching:**

- Test with `validate-rule-globs.py`
- Check pattern syntax (use `*` not regex)
- Verify file paths match expected format

**Broken cross-references:**

- Run `validate-rule-links.py`
- Fix paths: Use `../../docs/` from `.cursor/rules/`
- Remove links to non-existent files

**Metadata index out of sync:**

- Run `generate-rule-metadata.py` to regenerate
- Check for YAML parsing errors
- Verify all rule files have valid frontmatter

See [Rule Maintenance Guide](CURSOR_RULES_MAINTENANCE.md) for complete details.

## Troubleshooting recurring issues

- **Generic or vague plans** → reiterate that each step needs file paths, selectors, and validation. Ask Cursor to restate unclear steps.
- **Repeated edit failures** → switch to Multi-Edit or manual `apply_patch` with explicit context instead of re-running the same command.
- **Unexpected layout changes** → review diff for utility-class edits; if present, revert and instruct Cursor to confine changes to specific node ranges.
- **Schema validation errors** → copy rendered JSON-LD into jsonlint.com or browser console, fix trailing commas or outdated URLs, and re-run validation.
- **Rule validation errors** → run `bash scripts/maintain-rules.sh` to identify issues, fix YAML frontmatter, update glob patterns, or regenerate `docs/ai/METADATA_INDEX.json`

## Dry run & handoff checklist

1. Run through one recently updated comparison page and confirm:
   - Hero section: logo preload tag intact, CTA buttons render, copy matches du tone.
   - Comparison table: rows align, numeric data accurate, Ordio column highlights benefit.
   - FAQ: toggles functional, each answer short, includes exactly one Ordio mention overall.
   - Schema + meta: JSON-LD validates, title/description reference current year, canonical URL correct.
2. Capture screenshots or DOM notes for regression tracking (hero, table, FAQ).
3. Note required follow-up tests (PageSpeed, mobile viewport) in the task handoff.

## Automation & tooling backlog

- Add a reusable Multi-Edit snippet for swapping comparison table rows given JSON input.
- **Schema validation:** `npm run validate:schema <file>` or `node scripts/validate-schema-jsonld.js <file.json|file.html>` to catch JSON-LD issues locally.
- **Full validation:** `make validate` runs lint, format check, schema, PHPStan, and markdown links. Use `make pre-deploy` before deployment.
- Create a VS Code or Cursor command palette entry that opens the hero, comparison table, and FAQ sections side-by-side for quick diff reviews.
- **Lighthouse CI:** Automated via `.github/workflows/lighthouse-ci.yml` (runs on PR/push). Run locally: `npm run lighthouse` (requires `@lhci/cli`).

By following this playbook, we keep comparison work predictable, efficient, and aligned with how Ordio presents itself to prospects.

## Page-Type-Specific Workflows

### Product Pages (`product_*.php`)

**When to use:** Marketing Ordio features (Schichtplanung, Zeiterfassung, Abwesenheiten, etc.)

**Key focus:**

- Benefit-driven copy (not feature lists)
- SoftwareApplication + Service schema
- CTA prominence (primary above fold, secondary throughout)
- Social proof (testimonials, ratings, customer logos)

**Prompt pattern:**

```
Update the Schichtplan product page `v2/pages/product_schichtplan_neu.php` (`/schichtplan`): refresh hero headline to emphasize [benefit], update feature sections or partials as needed, and align testimonials/FAQ JSON. Ensure SoftwareApplication schema includes latest pricing and features. Keep du tone, mention Ordio once per section. (Archived template `product_shiftplan.php` is not routed.)
```

**Validation:**

- Hero clearly states benefit
- Features outcome-focused
- Schema validates (SoftwareApplication, Service)
- CTAs prominent and functional

### Industry Pages (`industry_*.php`)

**When to use:** Targeting specific verticals (Gastronomie, Einzelhandel, Pflege, etc.)

**Key focus:**

- Industry-specific pain points and terminology
- Authentic use cases from that vertical
- Industry + Service schema
- Compliance context (ArbZG, Mindestlohn, etc.)

**Prompt pattern:**

```
Update the Gastronomie Branchen page `v2/pages/branchen_gastronomie_neu.php` (`/branchen/gastronomie`): adjust paid-LP overrides (`$lp` title/desc/H1), hero or scroll-feature copy, integrations/testimonial blocks, and FAQ content via [`gastronomie/faq-answers-optimized.json`](../content/pages/industry-pages/gastronomie/faq-answers-optimized.json). Keep `get_og_image_for_page('industry', 'gastronomie', …)` and WebPage/SoftwareApplication schema aligned with live pricing. Use authentic Gastronomie terminology, du tone. (Archived: `industry_hospitality.php` is not routed.)
```

**Validation:**

- Pain points authentic to vertical
- Use cases feel real
- Industry terminology correct
- Schema validates (Industry, Service)

### Tools Pages (`tools_*.php`)

**When to use:** Interactive calculators (Arbeitstage-Rechner, Kostenrechner, etc.)

**Research before substantive SEO/FAQ work:** Run `php v2/scripts/tools/run-tools-improvement-pipeline.php --tool={slug}` (min. Phase 1–2) so `docs/content/tools/{slug}/` holds keywords, PAA, competitor data, and outlines – see [TOOLS_CONTENT_WORKFLOW.md](../guides/tools-pages/TOOLS_CONTENT_WORKFLOW.md). After JSON exists, use **Serper / Fetch / Firecrawl** per [TOOLS_SERP_MCP_GUIDE.md](../guides/tools-pages/TOOLS_SERP_MCP_GUIDE.md). Skill: `ordio-tools-content-block`.

**Key focus:**

- Calculator logic and validation
- Real-time updates
- Export functionality (Excel, PDF, CSV)
- HowTo schema

**Prompt pattern:**

```
Update `v2/pages/tools_arbeitstage_rechner.php`: add [new input field], update calculation logic for [scenario], and ensure Excel export follows Ordio branding. Test with edge cases (empty inputs, large numbers). Keep du tone, dotted background pattern.
```

**Validation:**

- Calculator works with valid/invalid inputs
- Export functionality works
- Form heights consistent (3rem desktop, 3.5rem mobile)
- Schema validates (HowTo)

### Templates Pages (`templates_*.php`)

**When to use:** Downloadable Excel/PDF templates with customizers

**Key focus:**

- Customizer UI (opening hours, roles, breaks)
- Real-time preview
- Multi-format export (Excel, PDF, Ordio-CSV)
- Excel branding compliance [[memory:8147019]]

**Prompt pattern:**

```
Update `v2/pages/templates_dienstplan.php`: add [new customizer field], update preview rendering for [scenario], and ensure Excel export follows Ordio branding (no purple, proper column widths, no header borders). Test customizer state management.
```

**Validation:**

- Customizer UI functional
- Preview updates in real-time
- Excel export follows branding guidelines
- Schema validates (DigitalDocument, HowTo)

### Download Pages (`download_*.php`)

**When to use:** Gated content (PDFs, guides, checklists)

**Key focus:**

- HubSpot form integration
- File delivery (download or email)
- GDPR compliance (consent checkbox)
- DigitalDocument schema

**Prompt pattern:**

```
Update `v2/pages/download_lohnabrechnungen.php`: refresh hero copy to emphasize [benefit], update form fields to include [new field], and verify file download triggers correctly. Ensure GDPR consent checkbox present. Du tone.
```

**Validation:**

- Form validation works
- GDPR consent checkbox present
- File download/email delivery works
- Schema validates (DigitalDocument)

### Webinar Pages (`webinar_*.php`)

**When to use:** Event registration pages

**Key focus:**

- Event schema with accurate date/time (timezone!)
- Registration form (HubSpot)
- Calendar download (.ics file)
- Agenda clarity

**Prompt pattern:**

```
Update `v2/pages/webinar_sozialversicherung.php`: change webinar date to [new date/time with timezone], update agenda with [new topics], and verify calendar download (.ics) includes correct details. Test registration form. Du tone.
```

**Validation:**

- Date/time accurate (with timezone)
- Calendar file (.ics) valid
- Registration form works
- Schema validates (Event)

### Pillar Pages (`pillar_*.php`)

**When to use:** SEO content hubs (Dienstplan, Zeiterfassung)

**Key focus:**

- Comprehensive content (1500+ words)
- Internal linking strategy
- FAQ schema
- Keyword optimization

**Prompt pattern:**

```
Update `v2/pages/pillar_dienstplan.php`: add section on [topic], update internal links to include [new pages], and refresh FAQ with [new questions]. Ensure Article + FAQPage schema current. Du tone, keyword-optimized, natural Ordio mentions.
```

**Validation:**

- Content comprehensive and structured
- Internal links relevant and functional
- FAQ addresses common questions
- Schema validates (Article, FAQPage)

### Static Pages (`static_*.php`)

**When to use:** Legal, pricing, customers, about pages

**Key focus:**

- **Legal pages: HIGH PROTECTION** – changes require approval
- Pricing accuracy
- Customer logo permissions
- Compliance (GDPR, legal requirements)

**Prompt pattern:**

```
Update `v2/pages/static_pricing_new.php` (`/preise`): sync [`pricing-data.php`](../../v2/sections/pricing-data.php) and Product `price`/`priceValidUntil` in the page head JSON-LD, refresh [`comparison-table-data.json`](../../v2/data/comparison-table-data.json) if plan matrix changes, and keep [`pricing-faq.json`](../../v2/data/pricing-faq.json) + FAQPage parity. **Ordio free trial = 7 days** — align any new copy with [`pricing-documentation.md`](../content/pages/static-pages/pricing-documentation.md) § Ordio free trial (SSOT), form trust lines, and FAQs. Verify tooltips. Du tone. (Legacy `static_pricing.php` is not the canonical `/preise` file.)
```

```
Update `v2/pages/static_customers_new.php` (`/kunden`): keep [`customer-spotlights-data.php`](../../v2/data/customer-spotlights-data.php) in sync with Customer Spotlight carousel + head `VideoObject` JSON-LD; refresh [`misc-faqs/static_customers_new.json`](../../v2/data/misc-faqs/static_customers_new.json) + marketing FAQ include parity. Link internally to **`/kunden`** only (not `/kunden-neu`). See [kunden-documentation.md](../content/pages/static-pages/kunden-documentation.md). (Legacy `static_customers.php` is not routed for `/kunden`.)
```

**Validation:**

- Legal pages unchanged (unless approved)
- Pricing current and correct
- Customer logos have permission
- Schema validates (appropriate for page type)

### Homepage (`landingpage*.php`, `start*.php`)

**When to use:** Primary entry point

**Key focus:**

- Hero optimization (LCP, CLS)
- Value props (benefits, not features)
- Social proof (logos, testimonials, ratings)
- Multiple CTAs (primary above fold)

**Prompt pattern:**

```
Update `v2/pages/landingpage.php`: refresh hero headline to [new headline], update value props with [new benefits], and add testimonial from [customer]. Ensure hero image preloaded, LCP < 2.5s. Du tone, conversion-focused.
```

**Validation:**

- Hero headline clear and benefit-driven
- Performance optimized (LCP, CLS, PageSpeed)
- Social proof prominent
- Schema validates (WebSite, Organization)

### Base Components (`v2/base/*.php`)

**When to use:** Shared includes (header, footer, forms, etc.)

**⚠️ HIGH PROTECTION ZONE ⚠️**

**Key focus:**

- Changes impact ALL pages
- Require explicit approval
- Test extensively across page types
- Use conditional logic to isolate changes

**Prompt pattern:**

```
I need to update `v2/base/header.php` to [change]. This affects all Ordio pages. Should I proceed? I'll test on product, industry, tools, comparison, and homepage before finalizing.
```

**Validation:**

- User explicitly approved change
- Tested on multiple page types (5+)
- No unintended side effects
- Change documented with comments

### API Endpoints (`v2/api/*.php`)

**When to use:** Lead capture, HubSpot integration, file generation

**Key focus:**

- Input validation and sanitization
- Error handling (try-catch, logging)
- Response format (JSON with success/message/data)
- Security (CSRF, rate limiting)

**Prompt pattern:**

```
Update `v2/api/lead-capture.php`: add validation for [new field], improve error handling for [scenario], and ensure HubSpot integration logs to `logs/`. Test with valid/invalid inputs.
```

**Validation:**

- Input validation comprehensive
- Error handling robust
- Logging implemented
- Security measures in place

## Rule Decision Tree

```
Is the task about...
├─ Comparing Ordio to competitors? → comparison-pages-core/content/schema-meta.mdc
├─ Marketing an Ordio feature? → product-pages.mdc
├─ Targeting a specific industry? → industry-pages.mdc
├─ An interactive calculator? → tools-pages.mdc (+ tools-prioritization.mdc for tools SEO backlog docs)
├─ A downloadable template? → templates-pages.mdc
├─ Gated content download? → download-pages.mdc
├─ Webinar registration? → webinar-pages.mdc
├─ SEO content hub? → pillar-pages.mdc
├─ Legal/pricing/about page? → static-pages.mdc
├─ The homepage? → homepage.mdc
├─ Shared components (header/footer)? → base-components.mdc (HIGH PROTECTION)
├─ API/backend logic? → api-endpoints-core.mdc + api-endpoints-security.mdc or shiftops-backend.mdc
├─ ShiftOps frontend? → shiftops-frontend-core.mdc + shiftops-frontend-qa.mdc
└─ Everything else → global.mdc (always applies)
```

## Quick Reference

| Page Type  | Rule File(s)            | Key Schema            | Primary Focus               |
| ---------- | ----------------------- | --------------------- | --------------------------- |
| Comparison | comparison-pages-*.mdc | Table, Product        | Competitor positioning      |
| Product    | product-pages.mdc    | SoftwareApplication   | Benefit-driven marketing    |
| Industry   | industry-pages.mdc   | Industry, Service     | Vertical-specific messaging |
| Tools      | tools-pages.mdc      | HowTo                 | Calculator logic + export   |
| Templates  | templates-pages.mdc  | DigitalDocument       | Customizer + export         |
| Downloads  | download-pages.mdc   | DigitalDocument       | Gated content + forms       |
| Webinars   | webinar-pages.mdc    | Event                 | Registration + calendar     |
| Pillars    | pillar-pages.mdc     | Article, FAQPage      | SEO content + links         |
| Static     | static-pages.mdc     | Varies                | Legal/pricing accuracy      |
| Homepage   | homepage.mdc         | WebSite, Organization | Conversion + performance    |
| Base       | base-components.mdc  | N/A                   | HIGH PROTECTION             |
| API        | api-endpoints-*.mdc  | N/A                   | Validation + security       |

By following these page-type-specific workflows, we maintain consistency across all Ordio pages while respecting the unique requirements of each page type.