Engineering Handbook — AI Agent Entrypoint

Read this file before doing any work here. See the AI Agent Entrypoint pattern for why this file exists and what it must contain.

Repository Purpose

What: The single source of truth for how engineering works at Ontopix — its principles, reusable patterns, architectural decisions (ADRs), templates, and a catalog of resources.

Why: Humans and AI agents need one authoritative, versioned place to learn the conventions every Ontopix repository is expected to follow. This repo defines the standards that other repos reference; it does not contain product or service code.

Boundaries:

• This repository IS responsible for:
  • Principles (principles/) — durable engineering values
  • Patterns (patterns/) — proven, reusable solutions (e.g. AGENTS.md, Taskfile contract, infrastructure layout, repository structure)
  • Decisions (decisions/) — Architectural Decision Records (ADRs)
  • Templates (templates/) — ready-to-use starting points for new repos/files
  • Explainers (explainers/) and Resources (resources/)
• This repository is NOT responsible for:
  • Application, service, or infrastructure code (lives in the respective repos)
  • Enforcing standards at runtime (CI in each repo does that)
  • Design-system or brand assets (see ontopix/stylebook)

Quick Start

This is a documentation repository (Markdown rendered by the Ontopix docs portal). There is no build, test suite, or sandbox to run.

Available Operations

task --list

Trigger a docs portal rebuild

Content is published to the Ontopix docs portal. Pushes to the default branch trigger a rebuild automatically via .github/workflows/trigger-docs-rebuild.yml. To trigger one manually (requires DOCSDEV_AMPLIFY_WEBHOOK_URL):

task docs:trigger

Operational Instructions

Repository Layout

Adding or Changing Content

1. Create a <type>/* branch following the git conventions.
2. Edit or add Markdown under the correct directory above.
3. Keep front-matter (title, description, badges, navigation) consistent with neighbouring files so the docs portal renders correctly.
4. Cross-link related patterns/principles with relative paths.
5. Open a PR for review (see CODEOWNERS).

Adding an ADR

• Copy the numbering and structure of the latest decisions/adr-NNNN-*.md.
• ADRs are append-only history: supersede an existing ADR with a new one; do not rewrite a decision after it has been accepted.

Technology Stack

Primary format: Markdown (with YAML front-matter)

Published by: the Ontopix docs portal (Nuxt Content on AWS Amplify), rebuilt via webhook on push to the default branch.

Pattern References

This repository is the pattern library. Start here:

• Repository Structure — the MVR standard
• AI Agent Entrypoint
• Taskfile as Contract
• Infrastructure Layout
• Git Conventions
• Full index: patterns/README.md

Pattern Discrepancy Rule: If you detect that your work contradicts a documented pattern, you MUST:

1. Stop immediately.
2. Surface the discrepancy explicitly (which pattern, what it prescribes, what the work attempts).
3. Propose either Path A (evolve the pattern, with justification) or Path B (a justified, documented exception).

Do NOT proceed silently when patterns are violated. Because this repo defines the patterns, edits here change the standard for the whole organization — treat them accordingly.

Constraints and Invariants

• Accuracy over volume. Content must reflect current, approved practice. Do not document aspirational or unimplemented standards as if they were in force.
• ADRs are immutable once accepted. Record changes by superseding, not editing.
• No secrets, credentials, or customer data in any file.
• Reference, don't duplicate. Link to the canonical pattern/principle rather than copying its content.

Agent Escalation Rules

Stop and request human (or CEO/lead) review before:

• Changing or removing an existing principle or pattern that other repos rely on (this changes the org-wide standard).
• Adding, superseding, or reversing an ADR.
• Editing templates/* that seed every new repository.
• Any change whose blast radius is "every Ontopix repo," not just this one.

Routine additions (a new explainer, a new resource entry, fixing a typo or broken link) do not require escalation — open a normal PR.

Related Repositories

• ontopix/infra — global infrastructure
• ontopix/schemas — JSON Schemas
• ontopix/claude-setup — Claude Code plugins

Additional Resources

• Engineering Patterns
• Architectural Decisions
• Templates