# AGENTS.md

## Purpose

Describe how AI coding agents should work in this repository.

This file is intentionally small. It acts as the repository-level router and startup guide. Detailed rules live in focused files under `./.ai/skills/` and should be loaded only when relevant to the current task.

---

## Startup Instructions

Before working on any task:

1. Read this `AGENTS.md`.
2. Read the main skill index:

   ```text
   ./.ai/SKILLS.md
   ```

3. Load only the relevant skill files for the current task.
4. Follow project-specific instructions before general best practices.
5. Inspect existing code before introducing new patterns.
6. State important assumptions before making major changes.
7. Prefer small, focused, reviewable changes.

---

## Instruction Priority

When instructions conflict, follow this order:

1. User's current request
2. Safety, security, privacy, and data-loss prevention
3. This `AGENTS.md`
4. `./.ai/SKILLS.md`
5. Referenced files in `./.ai/skills/`
6. Existing project conventions
7. General best practices

---

## Project Summary

This project is a small PHP MVC framework called **MindVisionCode PHP**.

It is intentionally inspired by a Classic ASP MVC framework style:

- Central dispatcher
- Controllers and actions
- ViewModels
- Repository classes
- Simple validation
- Database migrations
- Small, readable files
- Minimal dependencies

Do **not** turn this project into Laravel, Symfony, Slim, CakePHP, or another large framework.

The goal is to keep the framework understandable, practical, and easy to extend.

---

## Main Route

Always start here:

```text
./.ai/SKILLS.md
```

Then load only the skill files needed for the task.

---

## Common Skill Routes

```text
PHP language, style, Composer, OOP:
./.ai/skills/php/SKILL.md

MVC framework architecture, routing, controllers, views, ViewModels:
./.ai/skills/mvc/SKILL.md

PDO, repositories, migrations, SQL, database safety:
./.ai/skills/database/SKILL.md

Input validation, escaping, passwords, sessions, secrets, web security:
./.ai/skills/security/SKILL.md

Tests, static analysis, quality gates, composer scripts:
./.ai/skills/testing/SKILL.md

Agent behavior, PR checklist, legacy policy, response format:
./.ai/skills/workflow/SKILL.md
```

---

## Response Format

For non-trivial tasks, respond using this structure:

```text
Goal:
Route:
Assumptions:
Plan:
Implementation:
Tests:
Risks:
```

For simple questions, answer directly.

---

## Framework Change Policy

The framework core may be modified to add functionality or optimize existing code, but **never silently**. Any time an agent identifies a change to framework-level code (dispatcher, routing, base controller, base repository, migration runner, validation engine, autoloader, or any file under `core/`), it must stop and present the following proposal to the user before writing a single line:

```text
FRAMEWORK CHANGE PROPOSAL
==========================
Issue:
  What problem or limitation was found, and where in the framework it lives.

Proposed Change:
  What would be added, modified, or removed.

Why It Is Needed:
  The specific reason application code cannot solve this without a framework change.

Risks / Dangers:
  - Breaking changes to existing controllers, repositories, or views
  - Behavioral differences across PHP versions
  - Security surface changes
  - Performance regressions
  - Any other relevant concerns

Benefits:
  - What improves or is unlocked by the change

Alternatives Considered:
  Any application-level workarounds that were ruled out and why.

Ai Agent Skills Update:
  - What skills need to be changed to support this framework-level change?

Awaiting your approval before proceeding. Reply YES to apply, NO to skip, or ask questions.
```

**Rules:**
- Do not apply the change until the user explicitly approves.
- If the user says NO, document the limitation as a comment or note and continue with the best available application-level workaround.
- Keep framework changes small and focused — one concern per change.
- After approval, note the change in the commit message so the history is clear.
- Update the proper skill file so that the new process can be applied to all future changes in this repository.
---

## Skill Feedback Rule

If project guidance is missing or unclear, suggest an update.

```text
Suggested SKILLS.md update:
- Add/update: ...
- Reason: ...
```