The Website’s Actual Instruction Files

These are authorized, dated examples from this website's actual working tree, reviewed 2026-10-15. Source text stays in English; explanations are localized. The raw downloads preserve the inspected file bytes. They are snapshots, not automatically synchronized with later instruction changes; review for drift when source changes.

The repository owner chose to present agent_instructions/SHAPE.md as a project example. Its identity/status as the canonical protected SHAPE-wide artifact is pending owner confirmation. No filename is prescribed universally. Its updated instructions accept prompts, conversations, and files without a formal specification before coding. They require comprehensive agent-maintained current-state specifications and explicitly human-authorized test execution. The snapshots reflect these updated project instructions.

Protected engineering rules require their authorized owner's decision; an agent cannot relax them to simplify implementation. Markdown cannot enforce immutability: repository permissions, tool boundaries and reviews matter. Unknown ownership must be confirmed with the repository owner. Read the repository model, real repository, and specification practice.

AGENTS.md · L1–L2 · 2026-10-15 · SHA-256: 934bc8e84ae1373ec2f962587c967cbf7a161309945f067ba6ef0942fce7bc2a

Verbatim source in English:

# AGENTS.md

Meaning: This real root file is more extensive than the minimal discovery example.

Rationale: Do not misrepresent a simplified sample as this source.

Example: Read every instruction file before editing.

Authority and modification: These are website project rules. Editing the real AGENTS.md requires explicit user instruction under its governance section; agents may propose changes in agents.extensions.md. This is not a universal SHAPE root inventory.

Related material: Repository walkthrough · Specification practice · Download actual snapshot

AGENTS.md · L3–L16 · 2026-10-15 · SHA-256: 934bc8e84ae1373ec2f962587c967cbf7a161309945f067ba6ef0942fce7bc2a

Verbatim source in English:

## Core Principles
- At the beginning of each development session, read all Markdown (.md) files in agent_instructions/ to establish project standards and constraints.
- During implementation, consult relevant instruction files as needed.
- All applicable instructions remain binding.
- Work autonomously using approved technologies, libraries, components, and established patterns.
- Do not implement custom functionality when an approved solution already meets the requirement.
- Before introducing a new dependency, architectural pattern, or design-system component, evaluate existing alternatives and request user approval. 
- Prioritize long-term maintainability. 
- Favor clear, modular, reusable implementations and established patterns. 
- Avoid unnecessary complexity, duplication, and technical debt.
- Changes to approved technologies or architecture must include corresponding documentation updates.
- Maintain comprehensive, logically organized current-state specifications for all implemented functionality, including changes requested through prompts or conversations. Follow SHAPE.md.

Meaning: Read all standing instructions, reuse approved solutions, keep changes maintainable, and seek decisions for new dependencies, architecture or shared components. Current-state specifications cover all implemented behavior, including changes requested through prompts or conversations.

Rationale: Autonomy depends on established constraints and synchronized documentation.

Example: Reuse an existing component; ask before adding a UI framework.

Authority and modification: These are website project rules. Editing the real AGENTS.md requires explicit user instruction under its governance section; agents may propose changes in agents.extensions.md. This is not a universal SHAPE root inventory.

Related material: Repository walkthrough · Specification practice · Download actual snapshot

AGENTS.md · L17–L25 · 2026-10-15 · SHA-256: 934bc8e84ae1373ec2f962587c967cbf7a161309945f067ba6ef0942fce7bc2a

Verbatim source in English:

## Libraries & Frameworks
- **Do not reinvent the wheel.**
- Prefer existing approved libraries, frameworks, and reusable components over custom implementations.
- Before implementing non-trivial functionality, evaluate whether an existing approved solution meets the requirement.
- If an approved solution is suitable, use it.
- If no approved solution is suitable, the agent may implement straightforward functionality using the existing stack.
- Introducing a new dependency requires explicit human approval.
- Avoid unnecessary dependencies for functionality that can be implemented simply with existing project capabilities.

Meaning: Evaluate approved libraries before custom work; simple existing-stack code is allowed when no approved solution fits, but new dependencies need explicit approval.

Rationale: Avoid duplicated capabilities and maintenance burden.

Example: Use the installed YAML parser rather than adding another.

Authority and modification: These are website project rules. Editing the real AGENTS.md requires explicit user instruction under its governance section; agents may propose changes in agents.extensions.md. This is not a universal SHAPE root inventory.

Related material: Repository walkthrough · Specification practice · Download actual snapshot

AGENTS.md · L26–L34 · 2026-10-15 · SHA-256: 934bc8e84ae1373ec2f962587c967cbf7a161309945f067ba6ef0942fce7bc2a

Verbatim source in English:

## Code Structure & File Size
- **DRY** - Don't Repeat Yourself
- **Modularize aggressively.** Build reusable components and extract shared logic into separate files whenever possible.
- **File size rules:**
  - Target: **≤ 200 lines per file**
  - Hard limit: **350 lines maximum**
  - Exceeding 200 lines requires explicit justification through unavoidable constraints.
  (Exception are seed data files, i18n files, static HTML  and *.md files.)

Meaning: Avoid duplication, extract shared logic, target 200 lines and respect the 350-line cap with the stated content exceptions.

Rationale: Small cohesive files remain reviewable.

Example: Split a large component rather than hiding complexity in one file.

Authority and modification: These are website project rules. Editing the real AGENTS.md requires explicit user instruction under its governance section; agents may propose changes in agents.extensions.md. This is not a universal SHAPE root inventory.

Related material: Repository walkthrough · Specification practice · Download actual snapshot

AGENTS.md · L35–L43 · 2026-10-15 · SHA-256: 934bc8e84ae1373ec2f962587c967cbf7a161309945f067ba6ef0942fce7bc2a

Verbatim source in English:

## Styling and UX
- Use token-driven styling (CSS variables) for colors, spacing, and typography.
- Ensure responsive layouts for mobile and desktop.
- Accessibility is required:
  - semantic structure
  - keyboard support
  - visible focus states
  - sufficient color contrast

Meaning: Use design tokens, responsive layouts, semantic structure, keyboard operation, visible focus and sufficient contrast.

Rationale: The interface must work across devices and access needs.

Example: Use a named focus token on a keyboard-operable link.

Authority and modification: These are website project rules. Editing the real AGENTS.md requires explicit user instruction under its governance section; agents may propose changes in agents.extensions.md. This is not a universal SHAPE root inventory.

Related material: Repository walkthrough · Specification practice · Download actual snapshot

AGENTS.md · L44–L48 · 2026-10-15 · SHA-256: 934bc8e84ae1373ec2f962587c967cbf7a161309945f067ba6ef0942fce7bc2a

Verbatim source in English:

## SEO and Content
- Define metadata per page.
- Keep heading hierarchy and link text meaningful.
- Tone must stay technical, credible, and business-focused.

Meaning: Provide page metadata, meaningful heading/link text and a technical business-focused tone.

Rationale: Readers and discovery systems need accurate context.

Example: Translate a new page description as well as its heading.

Authority and modification: These are website project rules. Editing the real AGENTS.md requires explicit user instruction under its governance section; agents may propose changes in agents.extensions.md. This is not a universal SHAPE root inventory.

Related material: Repository walkthrough · Specification practice · Download actual snapshot

AGENTS.md · L49–L56 · 2026-10-15 · SHA-256: 934bc8e84ae1373ec2f962587c967cbf7a161309945f067ba6ef0942fce7bc2a

Verbatim source in English:

## Preserve URLs and SEO Redirects
- Preserve existing public URLs when renaming, moving, or removing pages. Where necessary, implement permanent redirects (301 or 308) using mechanisms supported by the approved hosting and deployment architecture.
- Do not introduce unsupported runtime dependencies to implement redirects.
- Update internal links, canonical URLs, language alternates, and sitemap entries. Preserve query parameters where applicable. Never redirect unrelated or missing pages to the homepage.
- Before merging, audit route and slug changes against available Git history and existing redirects. Verify HTTP status codes, redirect destinations, and query parameter preservation. Prevent redirect loops and chains.
- If the approved architecture cannot support a required redirect, explain the limitation and request a human decision rather than silently breaking the existing URL.
- If no relevant replacement exists, obtain approval for an intentional page retirement (404 or 410). Never silently break an existing public URL.

Meaning: Keep routes or implement supported permanent redirects; audit history, links, canonicals, alternates, sitemap, query preservation, loops and chains; obtain a decision for retirement or unsupported migration.

Rationale: Published links remain a product commitment.

Example: Add a new child route without renaming an existing page.

Authority and modification: These are website project rules. Editing the real AGENTS.md requires explicit user instruction under its governance section; agents may propose changes in agents.extensions.md. This is not a universal SHAPE root inventory.

Related material: Repository walkthrough · Specification practice · Download actual snapshot

AGENTS.md · L57–L64 · 2026-10-15 · SHA-256: 934bc8e84ae1373ec2f962587c967cbf7a161309945f067ba6ef0942fce7bc2a

Verbatim source in English:

## Architecture & Separation of Concerns
- Enforce **clear separation of concerns** between:
  - Domain logic
  - Application logic
  - Infrastructure
  - UI
- Cross-layer coupling is discouraged and must be explicitly justified.

Meaning: Keep domain, application, infrastructure and UI responsibilities separate; justify cross-layer coupling.

Rationale: Layer boundaries make change effects understandable.

Example: Keep filesystem YAML reads on the server.

Authority and modification: These are website project rules. Editing the real AGENTS.md requires explicit user instruction under its governance section; agents may propose changes in agents.extensions.md. This is not a universal SHAPE root inventory.

Related material: Repository walkthrough · Specification practice · Download actual snapshot

AGENTS.md · L65–L82 · 2026-10-15 · SHA-256: 934bc8e84ae1373ec2f962587c967cbf7a161309945f067ba6ef0942fce7bc2a

Verbatim source in English:

## Front-End & Back-End Components
- Components must be canonical and reusable.
- Variants must be explicitly named, finite, and justified by a genuine functional or design requirement. 
- Do not introduce new variants when an existing one meets the need.

### UI Components (Critical)
- UI components (e.g. buttons, cards, headlines) must be **singular, reusable, and canonical**.
- Prefer existing, named component variants and design tokens.
- Reuse established components and styles wherever possible.
- Specifications may introduce local layout variations or component-specific styling without requiring prior approval.
- When a variation is likely to be reused, extend the existing component or propose an addition to the design system.
- Example (button):
  - Sizes: `small | medium | large`
  - Styles: `default | positive | warning`
- Inline styles are **forbidden**.
- Styles must be applied **only via named CSS classes, design tokens, or a theme system**.
- Request approval before introducing material changes to the shared design system, not for routine local styling decisions.

Meaning: Reuse singular named components, finite justified variants and tokens; avoid inline styles; local layout choices are allowed but material shared-system changes need approval.

Rationale: Prevent divergent copies of the same control.

Example: Use the existing secondary button variant.

Authority and modification: These are website project rules. Editing the real AGENTS.md requires explicit user instruction under its governance section; agents may propose changes in agents.extensions.md. This is not a universal SHAPE root inventory.

Related material: Repository walkthrough · Specification practice · Download actual snapshot

AGENTS.md · L83–L88 · 2026-10-15 · SHA-256: 934bc8e84ae1373ec2f962587c967cbf7a161309945f067ba6ef0942fce7bc2a

Verbatim source in English:

## Theming & Style Swappability
- All styling **must be theme-driven and fully swappable**.
- The application must support changing the entire visual appearance (e.g. green theme → red theme) **by swapping stylesheets, themes, or token definitions only**.
- No component may depend on hard-coded colors, fonts, spacing, or visual values.
- All visual properties must be derived from **design tokens or a centralized theming system**.

Meaning: Derive all visual properties from tokens or a centralized theme; components must not depend on hard-coded visual values.

Rationale: A theme swap should change the entire appearance.

Example: Read spacing and colors from central CSS variables.

Authority and modification: These are website project rules. Editing the real AGENTS.md requires explicit user instruction under its governance section; agents may propose changes in agents.extensions.md. This is not a universal SHAPE root inventory.

Related material: Repository walkthrough · Specification practice · Download actual snapshot

AGENTS.md · L89–L97 · 2026-10-15 · SHA-256: 934bc8e84ae1373ec2f962587c967cbf7a161309945f067ba6ef0942fce7bc2a

Verbatim source in English:

## Accessibility (a11y)
- Accessibility is **mandatory**, not optional.
- UI components must support:
  - Keyboard navigation
  - Focus management
  - Screen-reader compatibility
  - Sufficient color contrast
- Accessibility requirements apply to all variants of a component.

Meaning: Ensure keyboard operation, focus management, screen-reader compatibility and sufficient contrast for every variant.

Rationale: Accessibility cannot be an optional component mode.

Example: Preserve focus when closing the mobile menu.

Authority and modification: These are website project rules. Editing the real AGENTS.md requires explicit user instruction under its governance section; agents may propose changes in agents.extensions.md. This is not a universal SHAPE root inventory.

Related material: Repository walkthrough · Specification practice · Download actual snapshot

AGENTS.md · L98–L100 · 2026-10-15 · SHA-256: 934bc8e84ae1373ec2f962587c967cbf7a161309945f067ba6ef0942fce7bc2a

Verbatim source in English:

## Testing
+- Follow SHAPE.md for specification-driven test creation, maintenance, regression protection, and human-controlled execution.

Meaning: Follow SHAPE for proportional specification-driven coverage, regression protection and explicitly human-controlled execution; keep unexecuted verification visible.

Rationale: Accessibility cannot be an optional component mode.

Example: Preserve focus when closing the mobile menu.

Authority and modification: These are website project rules. Editing the real AGENTS.md requires explicit user instruction under its governance section; agents may propose changes in agents.extensions.md. This is not a universal SHAPE root inventory.

Related material: Repository walkthrough · Specification practice · Download actual snapshot

AGENTS.md · L101–L112 · 2026-10-15 · SHA-256: 934bc8e84ae1373ec2f962587c967cbf7a161309945f067ba6ef0942fce7bc2a

Verbatim source in English:

## Internationalization (i18n)

- **Required languages:** All user-facing content must support English (`en`), German (`de`), and Spanish (`es`) from the start.
- **No hardcoded content:** All user-facing text, including headings, paragraphs, navigation, buttons, metadata, accessibility labels, alt text, validation messages, and errors, must be stored in localized YAML files.
- **Markdown support:** Long-form content may use Markdown within designated YAML fields. Do not embed JSX, executable application code, CSS, or presentation logic in content files.
- **Complete translations:** All three languages must be provided for every implemented feature or page. Missing translations are not acceptable; never silently fall back to another language.
- **Consistent structure:** Maintain matching keys, section identifiers, data structures, and placeholders across all supported languages.
- **Shared components:** Reuse the same components and layouts across languages. Do not create language-specific component implementations or embed translation objects and language-dependent text conditions in UI code.
- **Translation maintenance:** Update all supported languages whenever user-facing content changes. Validate translation completeness and consistency before considering the work complete.
- **Architecture compliance:** Follow `ARCHITECTURE.md` for YAML content organization, Markdown rendering, translation loading, and localized routing.

Meaning: Keep every user-facing string in matching EN/DE/ES YAML; use designated Markdown without executable content and shared layouts; validate parity without silent fallback.

Rationale: One locale must not silently receive incomplete or foreign-language UI.

Example: Translate metadata and accessibility labels with article content.

Authority and modification: These are website project rules. Editing the real AGENTS.md requires explicit user instruction under its governance section; agents may propose changes in agents.extensions.md. This is not a universal SHAPE root inventory.

Related material: Repository walkthrough · Specification practice · Download actual snapshot

AGENTS.md · L113–L121 · 2026-10-15 · SHA-256: 934bc8e84ae1373ec2f962587c967cbf7a161309945f067ba6ef0942fce7bc2a

Verbatim source in English:

## Security
- **Never store sensitive information in files.**
- This includes (but is not limited to):
  - Passwords
  - API keys
  - Tokens
  - Secrets
  - License keys

Meaning: Do not put passwords, keys, tokens, secrets or license keys in files.

Rationale: Publication and version control can expose stored credentials.

Example: Keep the public example free of environment credentials.

Authority and modification: These are website project rules. Editing the real AGENTS.md requires explicit user instruction under its governance section; agents may propose changes in agents.extensions.md. This is not a universal SHAPE root inventory.

Related material: Repository walkthrough · Specification practice · Download actual snapshot

AGENTS.md · L122–L125 · 2026-10-15 · SHA-256: 934bc8e84ae1373ec2f962587c967cbf7a161309945f067ba6ef0942fce7bc2a

Verbatim source in English:

## Documentation Discipline
- Project documentation must remain **synchronized with implementation**.
- Outdated documentation is considered a defect.

Meaning: Update project documentation with the implementation; stale documentation is a defect.

Rationale: Later agents rely on durable context.

Example: Update current-state requirements when page behavior changes.

Authority and modification: These are website project rules. Editing the real AGENTS.md requires explicit user instruction under its governance section; agents may propose changes in agents.extensions.md. This is not a universal SHAPE root inventory.

Related material: Repository walkthrough · Specification practice · Download actual snapshot

AGENTS.md · L126–L143 · 2026-10-15 · SHA-256: 934bc8e84ae1373ec2f962587c967cbf7a161309945f067ba6ef0942fce7bc2a

Verbatim source in English:

## AGENTS.md Governance (Strict)
- **The agent is forbidden from editing `AGENTS.md` autonomously.**
- `AGENTS.md` may only be modified **upon explicit user instruction**.
- If the agent wishes to propose changes:
  - They must write them to **`agents.extensions.md`**
  - No automatic merging or implicit updates are allowed.

  ## Quality Gate
- Before merge:
  - lint passes
  - type-check passes
  - build passes
  - dictionary checks pass (`pnpm run test:i18n`)
- Keep files modular and readable; split large components early.

Meaning: Never edit AGENTS.md autonomously: explicit user instruction is required; proposals belong in agents.extensions.md. The attached quality gate requires lint, typecheck, build and i18n checks before merge.

Rationale: An agent cannot relax the rules governing itself to finish a feature.

Example: Leave this root file untouched while publishing a dated copy.

Authority and modification: These are website project rules. Editing the real AGENTS.md requires explicit user instruction under its governance section; agents may propose changes in agents.extensions.md. This is not a universal SHAPE root inventory.

Related material: Repository walkthrough · Specification practice · Download actual snapshot

agent_instructions/STACK.md · L1–L5 · 2026-10-15 · SHA-256: 27e47c46eb07b0f5748438b242396b4f683bbfafce9f902c30bc634e222d984d

Verbatim source in English:

# STACK.md

- `STACK.md` defines the approved technology stack for the project.

Meaning: This file defines the website stack, not SHAPE-wide technology.

Rationale: Project decisions need a stable reference.

Example: Read it before choosing a renderer.

Authority and modification: Website-specific instruction/context, not a universally mandated filename or technology. Confirm the authorized owner before changing the actual controlled source. OBJECTIVES.md is explicitly descriptive context; DESIGN.md includes proposed directions.

Related material: Repository walkthrough · Specification practice · Download actual snapshot

agent_instructions/STACK.md · L6–L13 · 2026-10-15 · SHA-256: 27e47c46eb07b0f5748438b242396b4f683bbfafce9f902c30bc634e222d984d

Verbatim source in English:

## Purpose and versioning

Approved technology stack for the **SHAPE Framework documentation website**. This is a simple, content-first, multilingual site.

- Select recent compatible **stable** releases when implementation begins.
- Record exact dependency versions in `package.json` and the chosen lockfile, not in this document.
- Update this file whenever an approved technology choice changes.

Meaning: Select stable compatible releases and keep exact versions in manifest/lockfile; document changed technology choices.

Rationale: Reproducibility differs from a prose version list.

Example: Update the lockfile after an approved dependency change.

Authority and modification: Website-specific instruction/context, not a universally mandated filename or technology. Confirm the authorized owner before changing the actual controlled source. OBJECTIVES.md is explicitly descriptive context; DESIGN.md includes proposed directions.

Related material: Repository walkthrough · Specification practice · Download actual snapshot

agent_instructions/STACK.md · L14–L21 · 2026-10-15 · SHA-256: 27e47c46eb07b0f5748438b242396b4f683bbfafce9f902c30bc634e222d984d

Verbatim source in English:

## Core stack

- **Next.js** with the **App Router**
- **React**
- **TypeScript**, with strict type checking
- Node.js LTS for development, build, and production runtime
- Package manager: **pnpm** (single lockfile)

Meaning: Use Next.js App Router, React, strict TypeScript, Node LTS and pnpm with one lockfile.

Rationale: A single approved ecosystem reduces accidental alternatives.

Example: Add a typed server-rendered page.

Authority and modification: Website-specific instruction/context, not a universally mandated filename or technology. Confirm the authorized owner before changing the actual controlled source. OBJECTIVES.md is explicitly descriptive context; DESIGN.md includes proposed directions.

Related material: Repository walkthrough · Specification practice · Download actual snapshot

agent_instructions/STACK.md · L22–L31 · 2026-10-15 · SHA-256: 27e47c46eb07b0f5748438b242396b4f683bbfafce9f902c30bc634e222d984d

Verbatim source in English:

## Rendering and Deployment

- **Next.js App Router** with Node.js runtime deployment.
- Prefer static prerendering for pages whose content is available at build time.
- Use React Server Components by default; Client Components only where browser interactions are necessary.
- Generate supported localized routes at build time using `generateStaticParams`.
- Production deployment targets **Namecheap shared hosting using cPanel's Node.js application environment**.
- No standalone API backend, database, or persistent application sessions are required.
- The application must be compatible with the Node.js startup mechanism supported by Namecheap/cPanel.

Meaning: Prerender known localized routes, prefer Server Components and use cPanel Node startup; no independent backend or database is required.

Rationale: Rendering must fit the approved hosting model.

Example: Generate the new localized routes at build time.

Authority and modification: Website-specific instruction/context, not a universally mandated filename or technology. Confirm the authorized owner before changing the actual controlled source. OBJECTIVES.md is explicitly descriptive context; DESIGN.md includes proposed directions.

Related material: Repository walkthrough · Specification practice · Download actual snapshot

agent_instructions/STACK.md · L32–L54 · 2026-10-15 · SHA-256: 27e47c46eb07b0f5748438b242396b4f683bbfafce9f902c30bc634e222d984d

Verbatim source in English:

## Styling and icons

- **CSS Modules** for component-level styles.
- **Global CSS custom properties** as design tokens for color, type, spacing and layout.
- Responsive, accessible layouts with semantic HTML.
- **Phosphor Icons, React package: `@phosphor-icons/react`.**
- **Default icon style: `weight="duotone"`** for consistent two-tone iconography.
- In Next.js Server Components, import the SSR-safe icons from **`@phosphor-icons/react/ssr`**.
- In Client Components, use the standard React package where needed.
- Import named icons individually; avoid wildcard imports and unnecessary icon-library wrappers.
- Use the icon's `currentColor`/CSS-based styling where possible. Decorative icons should not receive redundant accessibility labels; meaningful icons need localized accessible text.
- No Tailwind CSS or other component framework by default. Introduce only with a specific, approved reason.

Example usage:

```tsx
import { BookOpenIcon } from '@phosphor-icons/react/ssr';

export function SectionIcon() {
  return <BookOpenIcon weight="duotone" size={28} aria-hidden="true" />;
}
```

Meaning: Use CSS Modules/tokens, semantic responsive HTML and named duotone Phosphor imports, with SSR-safe server imports; do not add a UI framework casually.

Rationale: Shared styling and correct import boundaries avoid runtime problems.

Example: Reuse existing CSS and SSR-safe icons.

Authority and modification: Website-specific instruction/context, not a universally mandated filename or technology. Confirm the authorized owner before changing the actual controlled source. OBJECTIVES.md is explicitly descriptive context; DESIGN.md includes proposed directions.

Related material: Repository walkthrough · Specification practice · Download actual snapshot

agent_instructions/STACK.md · L55–L66 · 2026-10-15 · SHA-256: 27e47c46eb07b0f5748438b242396b4f683bbfafce9f902c30bc634e222d984d

Verbatim source in English:

## Content and Framework Documentation

- **YAML (`.yaml`)** for localized page content, metadata, headings, labels, and structured content sections.
- **Markdown** within designated YAML fields for long-form text, including headings, paragraphs, lists, links, tables, and code examples.
- **React** for content rendering and presentation.
- **TypeScript** for application logic and typed content models.
- No MDX or executable JSX within content files.
- No CMS, database, editorial API, or remote content-fetching dependency in the initial version.
- Diagrams are optimized static assets with editable, version-controlled sources.
- **Mermaid** for source-controlled technical diagrams, including workflows, architecture, and process diagrams.
- Render diagrams as static SVG assets at build time.

Meaning: Keep prose in YAML/Markdown, presentation in React and logic in TypeScript; no MDX/CMS/runtime remote editorial source. Mermaid sources produce static assets.

Rationale: Content must not execute application code.

Example: Publish an instruction excerpt as a fenced Markdown block.

Authority and modification: Website-specific instruction/context, not a universally mandated filename or technology. Confirm the authorized owner before changing the actual controlled source. OBJECTIVES.md is explicitly descriptive context; DESIGN.md includes proposed directions.

Related material: Repository walkthrough · Specification practice · Download actual snapshot

agent_instructions/STACK.md · L67–L81 · 2026-10-15 · SHA-256: 27e47c46eb07b0f5748438b242396b4f683bbfafce9f902c30bc634e222d984d

Verbatim source in English:

## Internationalization

- Supported locales: **`en`, `es`, `de`**.
- Translation structure: **`i18n/<locale>/<page>.yaml`**, supporting nested directories for nested pages.
- **`i18n/<locale>/common.yaml`** contains shared interface text.
- All page-specific copy and SEO metadata, including long-form sections, belong in the page's own YAML file.
- **`i18n/config.ts`**: Locale types, default language, canonical route IDs, and URL helpers.
- **`i18n/dictionaries.ts`**: Typed, server-only content registry and loader.
- All supported languages share the same React rendering components and structured-content schema.
- Default English URLs are unprefixed (e.g., `/organization`); localized counterparts use `/es/organization` and `/de/organization`.
- Explicit route mapping and statically generated localized pages; no middleware-based locale detection.
- Language switcher, localized page metadata, canonical URLs, `hreflang` alternates, and multilingual sitemap.
- No automatic English fallback for missing translations; incomplete content must fail validation.
- No dedicated runtime i18n framework initially.

Meaning: Keep EN/DE/ES content parity, unprefixed English URLs, explicit route mapping, localized metadata and no silent fallback; dictionaries stay server-only.

Rationale: Language is content, not three implementations.

Example: Use the same component for each translated page.

Authority and modification: Website-specific instruction/context, not a universally mandated filename or technology. Confirm the authorized owner before changing the actual controlled source. OBJECTIVES.md is explicitly descriptive context; DESIGN.md includes proposed directions.

Related material: Repository walkthrough · Specification practice · Download actual snapshot

agent_instructions/STACK.md · L82–L92 · 2026-10-15 · SHA-256: 27e47c46eb07b0f5748438b242396b4f683bbfafce9f902c30bc634e222d984d

Verbatim source in English:

## Testing and developer tooling

- **ESLint** — Linting and static code analysis.
- **Prettier** — Code formatting.
- **TypeScript (strict mode)** — Static type checking.
- **Vitest** — Unit and component testing.
- **React Testing Library** — React component testing.
- **Playwright** — Browser-based functional, end-to-end, and visual regression testing.
- **Node.js scripts** — Localization and route-integrity validation.
- Required release checks: lint, typecheck, i18n validation and static production build.

Meaning: ESLint, Prettier, TypeScript, Vitest, Testing Library, Playwright and Node checks serve distinct local checks; release gates include lint/types/i18n/build.

Rationale: A tool list does not establish independent test derivation or acceptance.

Example: Run only the checks authorized for the change.

Authority and modification: Website-specific instruction/context, not a universally mandated filename or technology. Confirm the authorized owner before changing the actual controlled source. OBJECTIVES.md is explicitly descriptive context; DESIGN.md includes proposed directions.

Related material: Repository walkthrough · Specification practice · Download actual snapshot

agent_instructions/STACK.md · L93–L100 · 2026-10-15 · SHA-256: 27e47c46eb07b0f5748438b242396b4f683bbfafce9f902c30bc634e222d984d

Verbatim source in English:

## Hosting

- **Primary hosting target:** Namecheap shared hosting with cPanel Node.js application support.
- Run the Next.js application using the hosting environment's supported Node.js startup configuration.
- Serve prerendered pages where possible.
- Use the configured public site origin for canonical URLs and sitemap generation.
- Do not introduce hosting-specific application services unless required.

Meaning: Use Namecheap/cPanel Node startup, prerendering and the configured public origin without extra hosting services.

Rationale: Deployment metadata must match the published site.

Example: Supply the HTTPS origin at build time.

Authority and modification: Website-specific instruction/context, not a universally mandated filename or technology. Confirm the authorized owner before changing the actual controlled source. OBJECTIVES.md is explicitly descriptive context; DESIGN.md includes proposed directions.

Related material: Repository walkthrough · Specification practice · Download actual snapshot

agent_instructions/STACK.md · L101–L108 · 2026-10-15 · SHA-256: 27e47c46eb07b0f5748438b242396b4f683bbfafce9f902c30bc634e222d984d

Verbatim source in English:

## Explicitly out of scope

- Databases and ORMs.
- Authentication, user accounts and session management.
- API servers, contact form submission services and transactional email.
- External CMS or remote editorial storage.
- Audience-specific duplicate content trees (leaders/business/technical) in the initial version.
- Production operational tooling unrelated to hosting the website.

Meaning: Do not introduce databases, accounts, APIs, CMS, transactions or unrelated production tooling for this documentation site.

Rationale: Scope boundaries prevent architecture drift.

Example: Keep reference examples as content, not a live account system.

Authority and modification: Website-specific instruction/context, not a universally mandated filename or technology. Confirm the authorized owner before changing the actual controlled source. OBJECTIVES.md is explicitly descriptive context; DESIGN.md includes proposed directions.

Related material: Repository walkthrough · Specification practice · Download actual snapshot

agent_instructions/STACK.md · L109–L123 · 2026-10-15 · SHA-256: 27e47c46eb07b0f5748438b242396b4f683bbfafce9f902c30bc634e222d984d

Verbatim source in English:

## Approved content pipeline and runtime decisions

The user approved these supporting libraries for the website implementation:

- `yaml`: parse local localized content files.
- `react-markdown` and `remark-gfm`: safe Markdown rendering, including tables.
- `rehype-highlight` and `highlight.js`: syntax highlighting in documentation examples.
- `@mermaid-js/mermaid-cli`: generate static SVG diagrams during the build.
- `tsx`: execute typed build and content-validation scripts.

Use **Node.js 24 LTS** for development, builds, and production to satisfy the installed toolchain's engine requirements. Exact compatible versions are recorded in `package.json` and `pnpm-lock.yaml`. ESLint 9 and TypeScript 6 are selected for compatibility with the Next.js ESLint plugins (which do not yet declare support for ESLint 10/TypeScript 7); exact versions remain in the manifest.

Use system sans-serif and monospace fonts through design tokens; no external font dependency is required. The reusable primitives listed in `DESIGN.md` are implemented locally with the approved React/CSS stack. The Namecheap/cPanel startup adapter is `server.js`; deployment preparation is documented in `docs/DEPLOYMENT.md`.

Use `next.config.mjs` with JSDoc typing for the Next.js configuration. Loading production configuration must not require SWC/native compiler bindings or runtime TypeScript transpilation. The application remains TypeScript; this configuration-file format avoids the GLIBC compatibility failure observed on the Namecheap account without adding dependencies or changing the runtime architecture.

Meaning: Use the specifically approved YAML/Markdown/highlighting/Mermaid/tsx libraries, Node 24, compatible lint/types, system fonts and plain-JavaScript Next configuration.

Rationale: The cPanel GLIBC constraint makes runtime native compilation unsuitable.

Example: Build locally and load next.config.mjs directly in production.

Authority and modification: Website-specific instruction/context, not a universally mandated filename or technology. Confirm the authorized owner before changing the actual controlled source. OBJECTIVES.md is explicitly descriptive context; DESIGN.md includes proposed directions.

Related material: Repository walkthrough · Specification practice · Download actual snapshot

agent_instructions/ARCHITECTURE.md · L1–L2 · 2026-10-15 · SHA-256: 78ce22152688fb56538059c24b945dd7879ab40978ea0e7b0a425a733cf893e7

Verbatim source in English:

## Internationalization (i18n) Architecture

Meaning: The opening heading declares the architecture’s first concern; it is this website’s content design, not a universal SHAPE layout.

Rationale: The first line explains the file’s purpose.

Example: Find the locale loading rules here.

Authority and modification: Website-specific instruction/context, not a universally mandated filename or technology. Confirm the authorized owner before changing the actual controlled source. OBJECTIVES.md is explicitly descriptive context; DESIGN.md includes proposed directions.

Related material: Repository walkthrough · Specification practice · Download actual snapshot

agent_instructions/ARCHITECTURE.md · L3–L32 · 2026-10-15 · SHA-256: 78ce22152688fb56538059c24b945dd7879ab40978ea0e7b0a425a733cf893e7

Verbatim source in English:

### Translation File Structure

Store all localized content in the `i18n/` directory, organized first by language and then by page or feature.

```text
i18n/
├── config.ts
├── dictionaries.ts
├── en/
│   ├── common.yaml
│   ├── home.yaml
│   ├── about.yaml
│   └── guides/
│       └── example.yaml
├── de/
│   ├── common.yaml
│   ├── home.yaml
│   ├── about.yaml
│   └── guides/
│       └── example.yaml
└── es/
    ├── common.yaml
    ├── home.yaml
    ├── about.yaml
    └── guides/
        └── example.yaml
```

The page and folder names above are illustrative. Actual files must match the application's pages and features.

Meaning: Use i18n/ locale directories and common/page/feature YAML; the example filenames are illustrative.

Rationale: Readers must distinguish structure from a mandatory page inventory.

Example: Add corresponding nested page files in each locale.

Authority and modification: Website-specific instruction/context, not a universally mandated filename or technology. Confirm the authorized owner before changing the actual controlled source. OBJECTIVES.md is explicitly descriptive context; DESIGN.md includes proposed directions.

Related material: Repository walkthrough · Specification practice · Download actual snapshot

agent_instructions/ARCHITECTURE.md · L33–L41 · 2026-10-15 · SHA-256: 78ce22152688fb56538059c24b945dd7879ab40978ea0e7b0a425a733cf893e7

Verbatim source in English:

### Translation Organization

- **Page files:** Each page has a corresponding YAML file containing its localized content, including long-form text, headings, metadata, labels, image descriptions, and captions.
- **Shared text:** `common.yaml` contains genuinely shared interface content, such as navigation labels, footer text, and reusable messages.
- **Reusable features:** Features with their own localized content may have dedicated YAML files.
- **Nested pages:** Nested routes may use matching subfolders.
- **Language parity:** All language directories must have corresponding files with matching keys, section identifiers, and data structures.
- **Shared identifiers:** Route identifiers, asset paths, technical identifiers, and other nontranslated data remain independent of language files.

Meaning: Keep page-specific text/metadata in page YAML, genuinely shared text in common files, matching locale keys/structures and nontranslated technical identifiers separate.

Rationale: Duplication and missing language data cause drift.

Example: Translate prose while retaining exact source paths.

Authority and modification: Website-specific instruction/context, not a universally mandated filename or technology. Confirm the authorized owner before changing the actual controlled source. OBJECTIVES.md is explicitly descriptive context; DESIGN.md includes proposed directions.

Related material: Repository walkthrough · Specification practice · Download actual snapshot

agent_instructions/ARCHITECTURE.md · L42–L50 · 2026-10-15 · SHA-256: 78ce22152688fb56538059c24b945dd7879ab40978ea0e7b0a425a733cf893e7

Verbatim source in English:

### Translation Loading

- `i18n/config.ts` defines supported locales, the default locale, and localized URL helpers.
- `i18n/dictionaries.ts` provides typed, server-only YAML loading.
- YAML content is parsed and validated against shared TypeScript content schemas at build time.
- Server Components load the required page and shared content.
- Client Components receive only the localized strings they need, rather than importing complete dictionaries.
- Shared React components render content for all languages.

Meaning: Locale/URL helpers and typed YAML loaders validate schemas at build time; Server Components load dictionaries and send only required text to clients.

Rationale: Filesystem and large dictionaries should not enter browser bundles.

Example: Use the existing getPage loader.

Authority and modification: Website-specific instruction/context, not a universally mandated filename or technology. Confirm the authorized owner before changing the actual controlled source. OBJECTIVES.md is explicitly descriptive context; DESIGN.md includes proposed directions.

Related material: Repository walkthrough · Specification practice · Download actual snapshot

agent_instructions/ARCHITECTURE.md · L51–L60 · 2026-10-15 · SHA-256: 78ce22152688fb56538059c24b945dd7879ab40978ea0e7b0a425a733cf893e7

Verbatim source in English:

### Content Rendering

- Designated YAML fields may contain Markdown-formatted text.
- A shared Markdown renderer converts these fields into React elements.
- Structured YAML sections may reference approved component types, such as articles, diagrams, and callouts.
- Section ordering is determined by the YAML content.
- Reusable React components control presentation, styling, and behavior.
- Content files contain no executable application code, JSX, CSS, or presentation logic.
- Raw HTML embedded in Markdown is not rendered.

Meaning: Render designated Markdown with shared components, content-driven section order and no executable JSX/CSS/application logic or raw HTML.

Rationale: Editorial content must not become an execution surface.

Example: Quote the real instruction as code, not executable JSX.

Authority and modification: Website-specific instruction/context, not a universally mandated filename or technology. Confirm the authorized owner before changing the actual controlled source. OBJECTIVES.md is explicitly descriptive context; DESIGN.md includes proposed directions.

Related material: Repository walkthrough · Specification practice · Download actual snapshot

agent_instructions/ARCHITECTURE.md · L61–L70 · 2026-10-15 · SHA-256: 78ce22152688fb56538059c24b945dd7879ab40978ea0e7b0a425a733cf893e7

Verbatim source in English:

### Localized Routing

- English is the default language and uses unprefixed URLs, such as `/about`.
- German uses `/de/`, such as `/de/about`.
- Spanish uses `/es/`, such as `/es/about`.
- Localized pages share the same underlying rendering components.
- Each localized page provides appropriate metadata, canonical URLs, and `hreflang` alternates.
- Language switching preserves the equivalent page whenever possible.
- Sitemaps include all published language variants.

Meaning: Keep English unprefixed, German /de and Spanish /es, shared rendering, equivalent language switches, canonicals/alternates and all variants in the sitemap.

Rationale: Translation must preserve page identity and discovery.

Example: Link a German walkthrough to its Spanish equivalent.

Authority and modification: Website-specific instruction/context, not a universally mandated filename or technology. Confirm the authorized owner before changing the actual controlled source. OBJECTIVES.md is explicitly descriptive context; DESIGN.md includes proposed directions.

Related material: Repository walkthrough · Specification practice · Download actual snapshot

agent_instructions/ARCHITECTURE.md · L71–L88 · 2026-10-15 · SHA-256: 78ce22152688fb56538059c24b945dd7879ab40978ea0e7b0a425a733cf893e7

Verbatim source in English:

## Website implementation boundaries

- `domain/`: page-content contracts, validation, canonical route inventory, and related-page relationships. No UI or filesystem imports.
- `infrastructure/`: server-only filesystem access and YAML parsing. Public content requests must match a canonical route and supported locale.
- `application/`: localized navigation and metadata assembly using the domain and content loaders.
- `i18n/`: shared locale/URL helpers, server content loader, and localized YAML files.
- `components/`: shared presentation. Small Client Components handle disclosure keyboard support, language-link context, copy controls, and localized recovery UI.
- `app/(english)/`, `app/(german)/de/`, and `app/(spanish)/es/`: thin explicit locale route adapters. Each has a static locale root layout and optional catch-all page; all three use the same `SiteDocument`, `WebsitePage`, metadata assembly, and recovery components. This keeps the document language fixed for each locale while generating all 111 known pages. No language-specific UI implementation or middleware locale detection is used.
- `app/sitemap.ts` and `app/robots.ts`: generated discovery endpoints, using the configured build-time public origin.
- `styles/tokens.css`: central theme. CSS Modules consume tokens. Breakpoint thresholds are named in the design implementation documentation; native media queries use literal thresholds because CSS custom properties cannot be used in media conditions.
- `diagrams/` and `public/diagrams/`: editable Mermaid sources and generated SVGs. Build colors derive from theme tokens and are converted to inherited CSS variables in the inline assets. Generated inline SVG style attributes are normalized into classes.
- `specifications/current/`: maintained current-state website requirements, separate from the preserved human-authored specification under `specifications/`.

All known pages are generated at build time. A minimal CommonJS startup adapter delegates requests to Next.js under cPanel Passenger; no domain or product behavior is implemented in that adapter. Local YAML content is the only content source, and filesystem access never enters Client Components. `SITE_URL` is a public build configuration value; the real production origin must be supplied before building for publication.

The Next.js configuration is `next.config.mjs`, a directly executable ECMAScript module with JSDoc typing. Production startup does not transpile a TypeScript configuration or load native compiler bindings. This keeps the prebuilt runtime compatible with the hosting account's older GLIBC while preserving the existing configuration settings; native build tooling remains a local build concern.

Meaning: Respect domain/application/infrastructure/UI/locale adapter boundaries, centralized tokens, canonical routes and static assets; filesystem never enters Client Components. The stated 111-page count is a dated project snapshot, not a framework limit.

Rationale: New content should extend the existing architecture rather than create parallel systems.

Example: Register a new child route and load its YAML server-side.

Authority and modification: Website-specific instruction/context, not a universally mandated filename or technology. Confirm the authorized owner before changing the actual controlled source. OBJECTIVES.md is explicitly descriptive context; DESIGN.md includes proposed directions.

Related material: Repository walkthrough · Specification practice · Download actual snapshot

agent_instructions/ARCHITECTURE.md · L89–L93 · 2026-10-15 · SHA-256: 78ce22152688fb56538059c24b945dd7879ab40978ea0e7b0a425a733cf893e7

Verbatim source in English:

## HTTP recovery documents

The build renders three small standalone recovery documents with React DOM from the same localized YAML and theme tokens. `routing-manifest.json` is generated from the canonical route registry and public assets. The cPanel startup adapter delegates known URLs and Next.js assets to Next.js; `infrastructure/recovery.cjs` returns a generated localized document with HTTP 404 for unknown GET/HEAD requests. This avoids a Next.js 16 initial-error-document limitation where the localized not-found UI is otherwise delivered only through hydration. No new public content route, redirect, dependency, or product business rule is introduced. Framework-level not-found boundaries remain available during development and internal client navigation.

The recovery renderer is a standalone HTML artifact, so native `<head>` and stylesheet links are intentional; Next.js document lint rules are disabled only for that renderer. It requires no JavaScript and is served with a restrictive Content Security Policy. Known asset/page routing remains owned by Next.js. The generated manifest prevents a separately maintained route inventory in the startup adapter.

Meaning: Generate localized script-free 404 documents from YAML/theme tokens and route unknown requests through the generated manifest; retain framework boundaries for development/client navigation.

Rationale: Unknown URLs need correct initial status and usable localized recovery.

Example: Add new known routes to the generated manifest, not a handwritten server list.

Authority and modification: Website-specific instruction/context, not a universally mandated filename or technology. Confirm the authorized owner before changing the actual controlled source. OBJECTIVES.md is explicitly descriptive context; DESIGN.md includes proposed directions.

Related material: Repository walkthrough · Specification practice · Download actual snapshot

agent_instructions/DESIGN.md · L1–L8 · 2026-10-15 · SHA-256: 5b7895bc23fb75686f80083d628fbf3d75bbefb234198915ab5156fbb1092cae

Verbatim source in English:

# DESIGN.md
- describes site wide design directions and inspiration

Status: Proposed visual direction (not pixel-exact reverse engineering)
References: 
- https://meeko-template.framer.website/
- https://meeko-template.framer.website/blog/design-choices-that-age-well-and-the-ones-you-will-regret-later

Meaning: The file declares site-wide design inspiration, not an enterprise-wide visual mandate.

Rationale: Project examples must preserve their stated status.

Example: Treat the cited template as inspiration, not licensed source material.

Authority and modification: Website-specific instruction/context, not a universally mandated filename or technology. Confirm the authorized owner before changing the actual controlled source. OBJECTIVES.md is explicitly descriptive context; DESIGN.md includes proposed directions.

Related material: Repository walkthrough · Specification practice · Download actual snapshot

agent_instructions/DESIGN.md · L9–L11 · 2026-10-15 · SHA-256: 5b7895bc23fb75686f80083d628fbf3d75bbefb234198915ab5156fbb1092cae

Verbatim source in English:

## Design goal
Build an original, accessible, responsive website for SHAPE (Spec-driven, Human-led, Agentic, Product, Engineering). Take inspiration from Meeko's pastel editorial aesthetic, bold typography, thin borders, generous whitespace, rounded cards, and friendly but restrained details. Do not copy the template's copyrighted images, text, illustrations, brand, or exact layout.

Meaning: Build an original responsive SHAPE site inspired by editorial patterns; do not copy protected images, text, branding or exact layout.

Rationale: Inspiration is not permission to reproduce assets.

Example: Reuse general spacing ideas while creating original content.

Authority and modification: Website-specific instruction/context, not a universally mandated filename or technology. Confirm the authorized owner before changing the actual controlled source. OBJECTIVES.md is explicitly descriptive context; DESIGN.md includes proposed directions.

Related material: Repository walkthrough · Specification practice · Download actual snapshot

agent_instructions/DESIGN.md · L12–L14 · 2026-10-15 · SHA-256: 5b7895bc23fb75686f80083d628fbf3d75bbefb234198915ab5156fbb1092cae

Verbatim source in English:

## Character
Clear, approachable, confident, contemporary, precise. Visual warmth on overview pages; increasing information density and restraint on technical documentation pages. Avoid generic dark AI gradients, neon, glassmorphism, and gratuitous animations.

Meaning: Keep the tone clear, warm and precise; reduce decoration in technical documentation and avoid the listed gratuitous effects.

Rationale: Readers need substance and legibility.

Example: Use the established light article presentation.

Authority and modification: Website-specific instruction/context, not a universally mandated filename or technology. Confirm the authorized owner before changing the actual controlled source. OBJECTIVES.md is explicitly descriptive context; DESIGN.md includes proposed directions.

Related material: Repository walkthrough · Specification practice · Download actual snapshot

agent_instructions/DESIGN.md · L15–L34 · 2026-10-15 · SHA-256: 5b7895bc23fb75686f80083d628fbf3d75bbefb234198915ab5156fbb1092cae

Verbatim source in English:

## Proposed design tokens (starting values; not measured from Meeko)
- `--color-background: #F0EFFF` (soft lavender)
- `--color-surface: #FFFFFF`
- `--color-surface-subtle: #FAFAFF`
- `--color-text: #161616`
- `--color-text-muted: #555563`
- `--color-border: #292929`
- `--color-accent-lavender: #DAD8FF`
- `--color-accent-pink: #F8DCE8`
- `--color-accent-yellow: #FBE59B`
- `--color-accent-blue: #DBEFFB`
- `--color-focus: #3448BC`
- `--radius-card: 20px`
- `--radius-button: 999px`
- `--border-thin: 1px solid var(--color-border)`
- `--container-width: 1200px`
- `--content-width: 760px`

Colors are approximate design proposals, not extracted site values. Confirm with screenshot comparisons before locking tokens.

Meaning: Treat the listed colors, widths and radii as centrally managed starting proposals, with confirmation before locking.

Rationale: Local color constants would defeat theme swapping.

Example: Consume the established token instead of duplicating its hex value.

Authority and modification: Website-specific instruction/context, not a universally mandated filename or technology. Confirm the authorized owner before changing the actual controlled source. OBJECTIVES.md is explicitly descriptive context; DESIGN.md includes proposed directions.

Related material: Repository walkthrough · Specification practice · Download actual snapshot

agent_instructions/DESIGN.md · L35–L42 · 2026-10-15 · SHA-256: 5b7895bc23fb75686f80083d628fbf3d75bbefb234198915ab5156fbb1092cae

Verbatim source in English:

## Typography
- Use a licensed, readily available geometric/grotesk sans-serif such as `Manrope`, with `Inter` as a body alternative and system sans fallback.
- Hero: `clamp(3rem, 6vw, 5.5rem)`, weight 700–800, line-height 1.03–1.1, slight negative letter spacing.
- H1 interior page: `clamp(2.5rem, 4vw, 4.5rem)`, weight 700–800.
- H2: `clamp(2rem, 3vw, 3rem)`; H3: `1.4–1.8rem`.
- Body: 16–18px, line-height 1.6–1.75; technical prose width around 65–75 characters.
- Avoid tiny gray text; honor WCAG contrast requirements.

Meaning: Use readable responsive headings/body/code measures and licensed fonts; the stack later selects system fonts for this implementation.

Rationale: A design proposal must be read alongside the approved stack.

Example: Keep existing token-driven typography without adding font dependencies.

Authority and modification: Website-specific instruction/context, not a universally mandated filename or technology. Confirm the authorized owner before changing the actual controlled source. OBJECTIVES.md is explicitly descriptive context; DESIGN.md includes proposed directions.

Related material: Repository walkthrough · Specification practice · Download actual snapshot

agent_instructions/DESIGN.md · L43–L50 · 2026-10-15 · SHA-256: 5b7895bc23fb75686f80083d628fbf3d75bbefb234198915ab5156fbb1092cae

Verbatim source in English:

## Layout
- Desktop site container around 1200px, with fluid side padding `clamp(20px, 4vw, 64px)`.
- Hero: large expressive heading, brief supporting statement, restrained supporting diagrams/graphics.
- Navigation: simple rounded white bar with subtle dark outline, clear active state, responsive mobile menu.
- Section gaps: generally 80–128px desktop and 48–72px mobile.
- Use cards to organize concepts; avoid cardifying every paragraph.
- Prefer asymmetrical editorial compositions for marketing pages, regular readable grids for docs.

Meaning: Use fluid containers, readable document widths, generous spacing and restrained cards without boxing every paragraph.

Rationale: Structure should support content rather than decorative repetition.

Example: Place new reference text in the existing article flow.

Authority and modification: Website-specific instruction/context, not a universally mandated filename or technology. Confirm the authorized owner before changing the actual controlled source. OBJECTIVES.md is explicitly descriptive context; DESIGN.md includes proposed directions.

Related material: Repository walkthrough · Specification practice · Download actual snapshot

agent_instructions/DESIGN.md · L51–L62 · 2026-10-15 · SHA-256: 5b7895bc23fb75686f80083d628fbf3d75bbefb234198915ab5156fbb1092cae

Verbatim source in English:

## Components
- `SiteHeader`: rounded white navigation, accessible keyboard states.
- `PrimaryButton`: high-contrast pill button; `SecondaryButton`: white pill with thin dark outline.
- `ConceptCard`: white surface, thin outline, 16–24px radius, generous internal padding, optional pastel accent.
- `SectionHeading`: strong title, compact introduction, optional eyebrow.
- `ProcessStep`: numbered stage with connectors; readable in vertical mobile view.
- `DiagramPanel`: neutral framed canvas with consistent typography and clear connectors.
- `Callout`: restrained accent tint, border, icon, clear semantic purpose.
- `ArticleLayout`: narrow reading column, headings with anchors, code blocks, tables, optional TOC.
- `CodeBlock`: accessible contrast, copy button, horizontal overflow handling, syntax highlighting.
- `Tabs`, `Accordion`: accessible and keyboard-operable; only use when information architecture warrants them.

Meaning: Use the named shared navigation, button, card, heading, process, diagram, callout and article/code patterns; tabs/disclosures only where warranted.

Rationale: One component vocabulary limits divergence.

Example: Reuse the canonical code block for instruction excerpts.

Authority and modification: Website-specific instruction/context, not a universally mandated filename or technology. Confirm the authorized owner before changing the actual controlled source. OBJECTIVES.md is explicitly descriptive context; DESIGN.md includes proposed directions.

Related material: Repository walkthrough · Specification practice · Download actual snapshot

agent_instructions/DESIGN.md · L63–L70 · 2026-10-15 · SHA-256: 5b7895bc23fb75686f80083d628fbf3d75bbefb234198915ab5156fbb1092cae

Verbatim source in English:

## SHAPE-specific pages
- Home: strong value proposition; 5 SHAPE principles as a visual system; links into Organization, Process, Artifacts, Practitioner Guides.
- Philosophy: editorial narrative, concept callouts, few decorations.
- Organization: pod/team model diagrams and responsibility cards.
- Process: numbered, connected steps with inputs, outputs, review checkpoints.
- Artifacts / repository structure: file-tree visualizations, copyable examples, precise tables.
- Practitioner guides: documentation-first layout, TOC, code and examples; white/light surfaces dominate.

Meaning: Marketing pages introduce concepts while practitioner/reference pages prioritize readable procedures, file examples and navigation.

Rationale: Different information density does not need separate design systems.

Example: Use source excerpts and a table of contents for this walkthrough.

Authority and modification: Website-specific instruction/context, not a universally mandated filename or technology. Confirm the authorized owner before changing the actual controlled source. OBJECTIVES.md is explicitly descriptive context; DESIGN.md includes proposed directions.

Related material: Repository walkthrough · Specification practice · Download actual snapshot

agent_instructions/DESIGN.md · L71–L76 · 2026-10-15 · SHA-256: 5b7895bc23fb75686f80083d628fbf3d75bbefb234198915ab5156fbb1092cae

Verbatim source in English:

## Interaction and motion
- Use subtle 150–250ms transitions for hover/focus, gentle scroll reveals only where meaningful.
- Honor `prefers-reduced-motion`.
- Do not gate important content behind animations, hover, or carousels.
- Ensure mobile navigation, all links and controls, forms, and accordion elements have keyboard and touch support.

Meaning: Keep transitions subtle, honor reduced motion, avoid hover-only content and maintain touch/keyboard operation.

Rationale: Motion must not gate information.

Example: Expose all directive text without requiring animation.

Authority and modification: Website-specific instruction/context, not a universally mandated filename or technology. Confirm the authorized owner before changing the actual controlled source. OBJECTIVES.md is explicitly descriptive context; DESIGN.md includes proposed directions.

Related material: Repository walkthrough · Specification practice · Download actual snapshot

agent_instructions/DESIGN.md · L77–L83 · 2026-10-15 · SHA-256: 5b7895bc23fb75686f80083d628fbf3d75bbefb234198915ab5156fbb1092cae

Verbatim source in English:

## Accessibility and responsiveness
- Aim at WCAG 2.2 AA contrast and interaction requirements.
- Responsive at common mobile, tablet, desktop widths; no horizontal scrolling.
- Maintain minimum comfortable 44x44px interactive targets where feasible.
- Distinguish headings semantically and maintain visible focus outlines.
- Test diagrams and wide technical tables on small screens.

Meaning: Aim for WCAG 2.2 AA, meaningful headings/focus/contrast, comfortable targets and no page overflow, including wide diagrams/tables.

Rationale: Technical references still need mobile and assistive access.

Example: Keep a wide source block within its scroll container.

Authority and modification: Website-specific instruction/context, not a universally mandated filename or technology. Confirm the authorized owner before changing the actual controlled source. OBJECTIVES.md is explicitly descriptive context; DESIGN.md includes proposed directions.

Related material: Repository walkthrough · Specification practice · Download actual snapshot

agent_instructions/DESIGN.md · L84–L92 · 2026-10-15 · SHA-256: 5b7895bc23fb75686f80083d628fbf3d75bbefb234198915ab5156fbb1092cae

Verbatim source in English:

## Implementation instructions for coding agent
1. Inspect the Meeko reference URL visually if browser access is available. Capture desktop and mobile screenshots of the homepage and representative interior pages; identify patterns, not source assets to reuse.
2. Implement design tokens centrally using CSS variables or the existing project's token mechanism. Do not hardcode one-off colors and spacing in page components.
3. Build a small library of reusable site components before expanding pages.
4. Implement the SHAPE content architecture rather than copying the portfolio template's page structure.
5. Compare the rendered homepage to the reference for overall feeling, spacing, typography, border treatments, and density. Refine design tokens and reusable components once.
6. Apply the same design system consistently to all new pages. Technical documentation should remain more restrained than the homepage.
7. Do not introduce third-party graphics, fonts, or illustrations without confirming license/usage rights.

Meaning: Inspect references only within authorized scope, centralize tokens, reuse primitives, compare meaningful results and confirm asset rights.

Rationale: The process should produce original maintainable presentation.

Example: Extend the existing article rather than cloning the inspiration template.

Authority and modification: Website-specific instruction/context, not a universally mandated filename or technology. Confirm the authorized owner before changing the actual controlled source. OBJECTIVES.md is explicitly descriptive context; DESIGN.md includes proposed directions.

Related material: Repository walkthrough · Specification practice · Download actual snapshot

agent_instructions/DESIGN.md · L93–L99 · 2026-10-15 · SHA-256: 5b7895bc23fb75686f80083d628fbf3d75bbefb234198915ab5156fbb1092cae

Verbatim source in English:

## Acceptance criteria
- Recognizably inspired by the reference's light pastel editorial aesthetic, without being a clone.
- One global token source for color, type, radii, spacing and content widths.
- Distinct and consistent reusable cards, navigation, buttons, callouts and diagrams.
- Responsive on mobile, tablet and desktop; no layout overflows.
- Technical content is readable, navigable and copyable.
- Accessible keyboard focus, sufficient contrast and reduced-motion behavior.

Meaning: Assess original editorial character, one token source, reusable patterns, responsiveness, reading/copying and accessible interaction.

Rationale: Passing functional tests alone does not establish visual acceptance.

Example: Ask humans to review readability while reporting actual checks.

Authority and modification: Website-specific instruction/context, not a universally mandated filename or technology. Confirm the authorized owner before changing the actual controlled source. OBJECTIVES.md is explicitly descriptive context; DESIGN.md includes proposed directions.

Related material: Repository walkthrough · Specification practice · Download actual snapshot

agent_instructions/OBJECTIVES.md · L1–L2 · 2026-10-15 · SHA-256: f89fb98ce58fd71fdf2ec4c6a2ab0a6de1b12fccfcf5f99c089708330099bcd3

Verbatim source in English:

# OBJECTIVES.md — SHAPE Framework Website

Meaning: The opening names the website objectives; its own authority section explicitly denies mandatory instruction status.

Rationale: A useful context file is not automatically a rulebook.

Example: Use it to understand audience before choosing examples.

Authority and modification: Website-specific instruction/context, not a universally mandated filename or technology. Confirm the authorized owner before changing the actual controlled source. OBJECTIVES.md is explicitly descriptive context; DESIGN.md includes proposed directions.

Related material: Repository walkthrough · Specification practice · Download actual snapshot

agent_instructions/OBJECTIVES.md · L3–L10 · 2026-10-15 · SHA-256: f89fb98ce58fd71fdf2ec4c6a2ab0a6de1b12fccfcf5f99c089708330099bcd3

Verbatim source in English:

## Purpose and Authority

This document provides business context to help coding agents make better decisions. It describes the product's purpose, objectives, audience, and desired outcomes.

**This is not an authoritative instruction file.** It does not define mandatory requirements, override specifications, or authorize changes to product scope.

Agents should use this context to inform their judgment when multiple valid implementation options exist.

Meaning: Use business context to choose among valid options; it cannot override specifications or authorize scope changes.

Rationale: Objectives inform judgment without granting permissions.

Example: Do not build accounts merely to pursue adoption goals.

Authority and modification: Website-specific instruction/context, not a universally mandated filename or technology. Confirm the authorized owner before changing the actual controlled source. OBJECTIVES.md is explicitly descriptive context; DESIGN.md includes proposed directions.

Related material: Repository walkthrough · Specification practice · Download actual snapshot

agent_instructions/OBJECTIVES.md · L11–L20 · 2026-10-15 · SHA-256: f89fb98ce58fd71fdf2ec4c6a2ab0a6de1b12fccfcf5f99c089708330099bcd3

Verbatim source in English:

## Product Vision

Establish SHAPE as a credible, practical, and accessible framework for enterprise agentic product engineering.

**SHAPE** stands for **Spec-driven, Human-led, Agentic Product Engineering**.

The framework enables organizations to develop software **at the speed of thought**, combining AI-assisted implementation with human accountability, architectural discipline, enterprise governance, and long-term product ownership.

The website should become the primary public resource for understanding, adopting, and applying SHAPE.

Meaning: Explain SHAPE as a credible enterprise engineering framework combining speed, accountability, governance and ownership.

Rationale: Public copy should avoid unsupported hype.

Example: Describe actual conventions instead of promising multipliers.

Authority and modification: Website-specific instruction/context, not a universally mandated filename or technology. Confirm the authorized owner before changing the actual controlled source. OBJECTIVES.md is explicitly descriptive context; DESIGN.md includes proposed directions.

Related material: Repository walkthrough · Specification practice · Download actual snapshot

agent_instructions/OBJECTIVES.md · L21–L31 · 2026-10-15 · SHA-256: f89fb98ce58fd71fdf2ec4c6a2ab0a6de1b12fccfcf5f99c089708330099bcd3

Verbatim source in English:

## Target Audience

The website serves four primary audiences:

- **Enterprise technology leaders:** Evaluating agentic development for organizational productivity, governance, and engineering effectiveness.
- **Product managers and business analysts:** Translating business requirements into specifications and working with coding agents.
- **Architects and engineering leaders:** Establishing approved architectures, technologies, reusable components, and secure development environments.
- **Product Engineers:** Implementing, maintaining, and evolving applications through specification-driven agentic development.

The initial website serves all audiences through one unified information architecture.

Meaning: Serve leaders, product/domain practitioners, architects and Product Engineers through one architecture.

Rationale: Examples should connect overview and technical needs.

Example: Link the homepage to both concepts and real instructions.

Authority and modification: Website-specific instruction/context, not a universally mandated filename or technology. Confirm the authorized owner before changing the actual controlled source. OBJECTIVES.md is explicitly descriptive context; DESIGN.md includes proposed directions.

Related material: Repository walkthrough · Specification practice · Download actual snapshot

agent_instructions/OBJECTIVES.md · L32–L39 · 2026-10-15 · SHA-256: f89fb98ce58fd71fdf2ec4c6a2ab0a6de1b12fccfcf5f99c089708330099bcd3

Verbatim source in English:

## Business Objectives

1. **Explain the framework:** Clearly communicate SHAPE's philosophy, organizational model, development process, and differentiators.
2. **Enable adoption:** Provide practical guides, examples, diagrams, and reusable templates that help organizations implement SHAPE.
3. **Establish credibility:** Demonstrate that agentic development can operate within enterprise engineering standards and governance.
4. **Provide a lasting reference:** Maintain a coherent, accessible body of framework knowledge that can evolve over time.
5. **Demonstrate SHAPE in practice:** Develop the website itself according to SHAPE principles.

Meaning: Explain adoption, practical guidance, credibility, lasting reference and the website as a demonstration.

Rationale: A framework site needs usable examples, not only positioning.

Example: Publish the verified repository walkthrough.

Authority and modification: Website-specific instruction/context, not a universally mandated filename or technology. Confirm the authorized owner before changing the actual controlled source. OBJECTIVES.md is explicitly descriptive context; DESIGN.md includes proposed directions.

Related material: Repository walkthrough · Specification practice · Download actual snapshot

agent_instructions/OBJECTIVES.md · L40–L55 · 2026-10-15 · SHA-256: f89fb98ce58fd71fdf2ec4c6a2ab0a6de1b12fccfcf5f99c089708330099bcd3

Verbatim source in English:

## Product Positioning

SHAPE is an **enterprise product engineering framework**, not a coding agent, programming language, or software development platform.

Its defining concepts include:

- Human authority over product intent, material decisions, and acceptance.
- Specifications driving both implementation and verification.
- Incremental development that preserves approved functionality.
- Enterprise-approved architecture, execution environments, libraries, and components.
- Small, AI-enabled teams with clearly defined responsibilities.
- Architects establishing technical foundations and supporting significant decisions.
- Product Engineers maintaining enduring ownership of their applications.

The website should emphasize practical engineering improvements rather than AI hype or unsupported productivity claims.

Meaning: Describe an operating model rather than a platform, with human authority, specifications, approved assets, small teams and bounded ownership.

Rationale: Framework claims must stay practical.

Example: Do not portray the website stack as universal SHAPE technology.

Authority and modification: Website-specific instruction/context, not a universally mandated filename or technology. Confirm the authorized owner before changing the actual controlled source. OBJECTIVES.md is explicitly descriptive context; DESIGN.md includes proposed directions.

Related material: Repository walkthrough · Specification practice · Download actual snapshot

agent_instructions/OBJECTIVES.md · L56–L71 · 2026-10-15 · SHA-256: f89fb98ce58fd71fdf2ec4c6a2ab0a6de1b12fccfcf5f99c089708330099bcd3

Verbatim source in English:

## Content and User Experience

The website should make complex engineering concepts understandable without oversimplifying them.

Its principal content areas are:

- **Philosophy:** Why SHAPE exists and its guiding principles.
- **Organization:** Roles, responsibilities, and the team operating model.
- **Process:** The development lifecycle from discovery and specification through user acceptance.
- **Artifacts:** Framework instructions, specifications, standards, and repository structures.
- **Practitioner Guides:** Practical instructions, examples, and reusable templates.

Visitors should be able to move naturally from high-level explanations to detailed guidance.

The experience should be modern, approachable, technically credible, readable, accessible, and consistent across English, German, and Spanish.

Meaning: Connect Philosophy, Organization, Process, Artifacts and Guides through readable multilingual navigation.

Rationale: Complex engineering should remain understandable.

Example: Reuse shared translated article layouts.

Authority and modification: Website-specific instruction/context, not a universally mandated filename or technology. Confirm the authorized owner before changing the actual controlled source. OBJECTIVES.md is explicitly descriptive context; DESIGN.md includes proposed directions.

Related material: Repository walkthrough · Specification practice · Download actual snapshot

agent_instructions/OBJECTIVES.md · L72–L82 · 2026-10-15 · SHA-256: f89fb98ce58fd71fdf2ec4c6a2ab0a6de1b12fccfcf5f99c089708330099bcd3

Verbatim source in English:

## Success Criteria

The website succeeds when:

- New visitors can quickly understand what SHAPE is and why it matters.
- Different audiences can find information relevant to their responsibilities.
- Practitioners can use the content to begin applying the framework.
- Explanations, diagrams, and examples remain internally consistent.
- Content can be expanded and maintained without unnecessary complexity.
- The website's development demonstrates SHAPE's own engineering principles.

Meaning: Help readers understand, find responsibilities, start applying SHAPE and maintain consistent expandable knowledge.

Rationale: These are goals, not fabricated measured outcomes.

Example: Describe verified examples without claiming adoption metrics.

Authority and modification: Website-specific instruction/context, not a universally mandated filename or technology. Confirm the authorized owner before changing the actual controlled source. OBJECTIVES.md is explicitly descriptive context; DESIGN.md includes proposed directions.

Related material: Repository walkthrough · Specification practice · Download actual snapshot

agent_instructions/OBJECTIVES.md · L83–L90 · 2026-10-15 · SHA-256: f89fb98ce58fd71fdf2ec4c6a2ab0a6de1b12fccfcf5f99c089708330099bcd3

Verbatim source in English:

## Scope Boundaries

The initial product is a **public framework documentation and adoption resource**.

It is not intended to provide a hosted coding-agent platform, project management application, user accounts, commercial transactions, or community forum.

Future capabilities may be considered separately.

Meaning: Keep the site a public documentation/adoption resource, not a hosted agent, commerce, account or community platform.

Rationale: Business scope prevents unnecessary infrastructure.

Example: Use downloadable examples instead of user accounts.

Authority and modification: Website-specific instruction/context, not a universally mandated filename or technology. Confirm the authorized owner before changing the actual controlled source. OBJECTIVES.md is explicitly descriptive context; DESIGN.md includes proposed directions.

Related material: Repository walkthrough · Specification practice · Download actual snapshot

agent_instructions/OBJECTIVES.md · L91–L101 · 2026-10-15 · SHA-256: f89fb98ce58fd71fdf2ec4c6a2ab0a6de1b12fccfcf5f99c089708330099bcd3

Verbatim source in English:

## Decision Guidance

When specifications allow multiple valid solutions, favor:

- Clarity over complexity.
- Practical guidance over abstract theory.
- Consistency over novelty.
- Substance over marketing.
- Maintainability over shortcuts.
- Flexibility over unnecessary bureaucracy.

**Specifications define what to build. These objectives provide the business context to help make better decisions.**

Meaning: Favor clarity, practicality, consistency, substance, maintainability and proportionate flexibility within governing requirements.

Rationale: Business objectives support judgment rather than expand authority.

Example: Choose the existing content system for the reference pages.

Authority and modification: Website-specific instruction/context, not a universally mandated filename or technology. Confirm the authorized owner before changing the actual controlled source. OBJECTIVES.md is explicitly descriptive context; DESIGN.md includes proposed directions.

Related material: Repository walkthrough · Specification practice · Download actual snapshot