Imported from vminh16/Visual_Oxyz_Tutor (AGENTS.md). Install upstream with npx skills add vminh16/Visual_Oxyz_Tutor. Copyright stays with the author.

Visual Oxyz Tutor — Agent Instructions

Canonical instruction entry point for coding agents. Keep this file concise; project truth lives in docs/.

Project Mission

Visual Oxyz Tutor helps upper-secondary students understand Oxyz coordinate geometry through:

Problem Understanding → Interactive 3D Visualization → Guided Reasoning → Mathematical Verification

The product is a tutor, not an answer-first solver. Visualization is a learning surface, not decoration. Mathematical correctness outranks fluent AI output.

Start with:

• docs/start-here/README.md
• docs/DOCUMENTATION_INDEX.md
• docs/product/PRODUCT_OVERVIEW.md
• docs/product/SCOPE_AND_PRINCIPLES.md

Then read only the documents relevant to the current task.

Sources of Truth

• Product direction: docs/product/
• Oxyz scope/problem families: docs/learning-domain/
• Capability behavior: docs/capabilities/
• User flows/UX: docs/experience/
• Architecture/trust boundaries: docs/architecture/
• Evaluation/release gates: docs/quality/
• Design specs/execution plans: docs/delivery/

If code, a temporary plan, or a prompt conflicts with an Accepted canonical document, surface the conflict instead of silently choosing one.

Read by Task

Problem understanding: docs/capabilities/PROBLEM_UNDERSTANDING.md, docs/learning-domain/PROBLEM_TYPE_CATALOG.md, docs/architecture/AI_AND_MATH_BOUNDARIES.md.

3D visualization: docs/capabilities/INTERACTIVE_3D_VISUALIZATION.md, docs/experience/UX_PRINCIPLES.md, docs/architecture/SYSTEM_DIRECTION.md.

Tutor behavior: docs/capabilities/GUIDED_TUTORING.md, docs/learning-domain/LEARNING_WORKFLOW.md, docs/learning-domain/PEDAGOGICAL_GUARDRAILS.md.

Math verification & orchestration: docs/capabilities/MATH_VERIFICATION.md, docs/architecture/AI_AND_MATH_BOUNDARIES.md, docs/architecture/AGENTIC_MATH_ORCHESTRATION.md, docs/quality/ACCEPTANCE_CRITERIA.md.

End-to-end/release: docs/quality/EVALUATION_STRATEGY.md, docs/quality/ACCEPTANCE_CRITERIA.md, docs/capabilities/CAPABILITY_STATUS.md.

Scope changes: docs/product/SCOPE_AND_PRINCIPLES.md, docs/product/DECISIONS.md, docs/learning-domain/OXYZ_LEARNING_SCOPE.md.

Non-Negotiable Product Rules

1. Keep the MVP focused on Oxyz coordinate geometry.
2. Do not turn the product into a generic math chatbot or general solver.
3. Do not add adjacent math domains without an explicit accepted scope decision.
4. Default to guided reasoning before revealing a complete solution.
5. Visualization must support the current mathematical reasoning step.
6. Make ambiguity, unsupported cases, and unverifiable results explicit.
7. Never claim a capability is implemented or verified without repository and evaluation evidence.

AI, Math, and Visualization Boundary

docs/architecture/AI_AND_MATH_BOUNDARIES.md is a hard architectural constraint.

• AI: language interpretation, explanation, hints, conversational flexibility.
• Deterministic math/verifier: mathematical truth within supported verifiable scope.
• Visualization: render canonical geometry; never decide mathematical truth from appearance.
• Tutor orchestration: choose how to guide; never override verified mathematics.

When components disagree: verified mathematics wins over AI wording; canonical geometry wins over visual appearance; unsupported/unverifiable cases remain explicit. Never hide a failed mathematical result behind confident prose.

Canonical State

Problem understanding, visualization, tutoring, and verification must share one canonical problem/geometry state.

Do not create independent hidden interpretations of the same problem inside separate UI, AI, or verifier modules. Changing the canonical representation is an architectural change and requires review of affected docs, interfaces, and tests.

Engineering Approach

Before editing:

1. Inspect the current repository and existing implementation.
2. Read the relevant canonical docs.
3. Identify the smallest coherent change.
4. Reuse established patterns unless they conflict with project rules.
5. State material assumptions that cannot be verified.

During implementation:

• Prefer simple, explicit boundaries over clever abstractions.
• Keep modules focused on one responsibility.
• Do not introduce a new framework, state system, rendering engine, model provider, database, or major dependency without concrete need.
• Explain why a new dependency is necessary when adding one.
• Keep mock data and service adapters outside presentation components.
• Do not embed provider-specific AI, backend, or mathematical business logic in UI components.
• Treat interactive visualization as expensive; unrelated UI updates should not rebuild the scene unnecessarily.
• Preserve responsive and accessible behavior.

Frontend Constraints

The visual hierarchy is: interactive geometry → current tutor guidance → secondary session navigation.

Desktop: collapsible session rail on the far left, dominant visualization workspace, tutor panel on the right at roughly 30% of usable workspace.

Mobile: do not compress the desktop split. Keep visualization primary and expose tutor/history through a drawer, bottom sheet, or focused view switch.

Problem upload/input precedes the main learning workspace.

Delivery Workflow

Follow docs/delivery/README.md.

Small bounded changes may be implemented directly after reading relevant docs. For new subsystems, cross-capability changes, meaningful interface changes, or multi-step architectural work:

1. Create/update a design spec in docs/delivery/specs/.
2. Get the design reviewed before implementation.
3. Create an execution plan in docs/delivery/plans/ when useful.
4. Implement against the accepted spec.
5. Promote durable decisions back into canonical docs.

Delivery documents are temporary execution truth, not permanent product truth.

Testing and Evaluation

Use docs/quality/EVALUATION_STRATEGY.md and docs/quality/ACCEPTANCE_CRITERIA.md.

The primary evaluation surface is intentionally small: representative end-to-end metrics, a few general system metrics, and one primary metric per core capability. Diagnostic metrics exist for debugging, not for inflating the headline scorecard.

For code changes:

• Add/update tests for changed behavior and regression coverage for bugs.
• Include invalid, ambiguous, unsupported, and boundary cases when relevant.
• For math verification, explicitly test false-correct behavior.
• For visualization, test semantic scene fidelity, not only successful rendering.
• For tutoring, test mathematical validity and support-level behavior, not only text quality.

Verification Before Completion

Never claim completion from inspection alone.

Before reporting completion:

1. Discover and run the repository's relevant formatter/linter/type-check/build/test commands.
2. Run focused tests for changed behavior and broader regression checks when shared interfaces/state changed.
3. Review the diff for scope creep, stale mocks, dead code, and unrelated edits.
4. Re-check affected canonical docs and acceptance criteria.
5. Report failures and unverified areas explicitly.

Do not invent commands; discover them from repository configuration and existing scripts.

Documentation and Scope Control

• Update canonical docs when a durable decision changes; use delivery docs for temporary implementation detail.
• Keep canonical docs technology-light unless a technology choice becomes an accepted constraint.
• Never silently change Accepted product/architecture direction as part of implementation.
• Keep docs/capabilities/CAPABILITY_STATUS.md aligned with repository evidence.

Stop and surface the issue when work conflicts with Accepted docs, expands beyond declared Oxyz scope, creates competing sources of truth, cannot preserve mathematical safety, requires a major unapproved architectural dependency, or requires weakening acceptance criteria.

Prefer a smaller correct implementation over a broader unverified one.

Definition of Done

A task is done only when applicable conditions are satisfied:

• requested behavior exists and relevant tests pass;
• no known critical mathematical correctness issue is introduced;
• AI/math/visualization boundaries remain intact;
• affected responsive/accessibility behavior is preserved;
• failure and uncertainty states are explicit;
• no accidental scope expansion occurred;
• durable documentation changes are reflected in canonical docs;
• verification evidence and remaining limitations are reported.

Agent Compatibility

• Codex reads this AGENTS.md directly.
• Claude Code uses the repository CLAUDE.md, which imports this file.
• Gemini CLI / compatible Google coding agents should be configured to include AGENTS.md as project context when it is not loaded automatically.

Direct user instructions take precedence, but project-truth conflicts must be explained rather than hidden.