Imported from ibrahimmaher2503-source/education_platform (AGENTS.md). Install upstream with npx skills add ibrahimmaher2503-source/education_platform. Copyright stays with the author.

AGENTS.md

1. Purpose

This file defines the mandatory rules that every AI coding agent must follow while working on the LMS project.

The project is an educational platform for primary and preparatory school students. A student subscribes to a package linked to a specific grade, academic year, and term. The subscription unlocks all included subjects for that academic context.

The AI must implement the system incrementally according to the documentation, milestones, acceptance criteria, security rules, and current project state.

2. Mandatory Reading Order

Before changing any code, read the following files in order:

1. AGENTS.md
2. README.md
3. All product and technical documentation inside docs/
4. .ai/HANDOFF.md
5. .ai/CURRENT_MILESTONE.md
6. .ai/PROGRESS.md
7. .ai/BLOCKERS.md
8. .ai/DECISIONS.md
9. .ai/TEST_RESULTS.md

After reading, inspect the existing codebase before assuming that any feature is missing.

3. Core Business Rules

The following rules are mandatory and must not be changed silently:

1. A parent has an independent account.
2. A parent can be linked to one or more students.
3. A subscription is activated for a specific student.
4. A subscription must not automatically unlock content for all children linked to the same parent.
5. A student is linked to a grade, academic year, and term through an academic enrollment or equivalent academic context.
6. A valid subscription unlocks the subjects included in the package for that student and academic context.
7. Package, billing plan, order, payment, and subscription are separate concepts and entities.
8. Package differences may be based on service level, follow-up, live classes, reports, and support—not necessarily subject availability.
9. Teachers may only access assigned grades, subjects, classes, and students.
10. Parents may only access students explicitly linked to their accounts.
11. Students may only access content covered by an active subscription.
12. Administrative staff access must be controlled by explicit permissions.
13. Authorization must be enforced on the server, not only by hiding UI actions.
14. Critical operations must be added to the audit log.
15. Payment confirmation must be idempotent and must not create duplicate subscriptions or invoices.

4. Required Development Cycle

For every task, follow this exact cycle:

1. Read the related requirement and acceptance criteria.
2. Inspect the current implementation.
3. Add or update the task in .ai/CURRENT_MILESTONE.md.
4. Write a short implementation plan.
5. Implement only the relevant change.
6. Add validation.
7. Add authorization.
8. Handle failure and edge cases.
9. Add or update tests.
10. Run relevant tests and quality checks.
11. Fix failures caused by the change.
12. Review security and data access.
13. Update the milestone checklist.
14. Update .ai/PROGRESS.md.
15. Update .ai/TEST_RESULTS.md.
16. Update .ai/HANDOFF.md.
17. Continue automatically to the next unblocked task.

Do not stop after writing a plan.

5. Continuation Rules

Continue working while there are executable, unblocked tasks.

Do not request confirmation after every task.

Do not stop merely to provide a progress summary.

When a missing external decision does not block the rest of the implementation:

• Record it in .ai/BLOCKERS.md.
• Create an interface, adapter, fake, stub, or mock implementation.
• Continue with all unblocked work.

Examples:

• Unknown payment provider: create PaymentGatewayInterface and a fake sandbox implementation.
• Unknown live-class provider: create LiveClassProviderInterface.
• Email or SMS credentials unavailable: use fake notification channels in development and tests.

6. Allowed Stop Conditions

The AI may stop only when one of the following is true:

1. A required secret or credential cannot be replaced by a safe fake.
2. A destructive, irreversible action requires explicit approval.
3. A major business decision has multiple structurally different options.
4. The development environment is completely unusable.
5. Two authoritative project documents directly conflict and context cannot resolve the conflict.
6. A required third-party service cannot be simulated and blocks all further work.

Before stopping:

• Finish every other unblocked task.
• Record the blocker in .ai/BLOCKERS.md.
• Update .ai/HANDOFF.md.
• List the available options and impact of each.
• Ask for one precise decision only.

7. Completion Rules

The words done, completed, or finished may only be used when:

• All applicable acceptance criteria are verified.
• Required validation exists.
• Server-side authorization exists.
• Relevant automated tests exist.
• Relevant tests pass.
• Failure states and edge cases are handled.
• Database constraints and indexes are reviewed.
• Documentation and checklists are updated.
• .ai/PROGRESS.md, .ai/TEST_RESULTS.md, and .ai/HANDOFF.md are updated.

Creating files without integrating or testing them is not completion.

A page that renders but does not enforce permissions is incomplete.

A feature using hardcoded production data is incomplete unless the requirement explicitly requests a prototype.

Blocked tasks must never be marked complete.

8. Architecture Rules

Follow the architecture documented in docs/.

Default rules unless the existing project defines stricter conventions:

• Controllers and UI resources should remain thin.
• Business logic belongs in services, actions, or domain classes.
• Validation belongs in dedicated request or form validation layers.
• Authorization belongs in policies, gates, permissions, and query scoping.
• Multi-step writes must use database transactions.
• Long-running work should use queued jobs.
• Side effects should use events/listeners when useful.
• External providers must be accessed through interfaces or adapters.
• Reuse existing patterns before introducing new abstractions.
• Do not install a package unless it provides clear value and is documented.
• Do not modify unrelated modules.
• Do not duplicate business logic.

9. Database Rules

• Use foreign keys where appropriate.
• Add indexes for common filters, joins, status fields, dates, and lookup columns.
• Use unique constraints to protect business invariants.
• Do not edit an already-shared migration; create a new migration.
• Never run destructive production commands.
• Use transactions for checkout, payment confirmation, enrollment, grading publication, and similar workflows.
• Preserve historical financial and academic records.
• Prefer status transitions over destructive deletion for financial records.
• Define clear handling for soft deletes and archived academic data.
• Prevent duplicate active subscriptions where business rules prohibit them.

10. Authorization Rules

At minimum, verify:

• A student cannot access another student’s records.
• A parent cannot access an unlinked student.
• A teacher cannot access unassigned subjects or students.
• A staff member cannot perform actions outside granted permissions.
• An expired subscription cannot unlock protected content.
• A subscription for one child cannot unlock another child.
• Hidden UI actions remain inaccessible through direct requests.
• Reports and file downloads enforce the same access rules as pages and APIs.

Every critical permission rule must have a negative test.

11. Testing Rules

For each feature, cover as applicable:

• Happy path.
• Validation failures.
• Authentication.
• Authorization and ownership.
• Edge cases.
• State transitions.
• Duplicate requests.
• Transaction rollback.
• File upload restrictions.
• Subscription expiry.
• Time-bound exam behavior.
• Calculation accuracy.
• Notifications.
• Audit logging.

After each task: run targeted tests.

After each module: run module tests.

After each milestone: run the full available test suite and quality checks.

Do not hide, delete, or skip failing tests to obtain a green result.

12. Git Rules

• Work on a dedicated branch.
• Keep commits small and meaningful.
• Do not commit secrets, local environment files, or generated sensitive data.
• Suggested commit formats:

feat(auth): add parent and student profiles
feat(academics): add academic terms and grade assignments
test(subscriptions): protect student-scoped access
fix(exams): prevent submission after deadline
docs(ai): update milestone handoff

13. Required AI State Files

The AI must keep the following files current:

• .ai/CURRENT_MILESTONE.md
• .ai/PROGRESS.md
• .ai/BLOCKERS.md
• .ai/TEST_RESULTS.md
• .ai/DECISIONS.md
• .ai/HANDOFF.md

The codebase and test results are the source of truth. If a state file conflicts with the code, inspect the implementation, correct the state file, and document the correction.

14. Final Project Review

Before declaring the whole project ready, perform independent reviews for:

1. PRD coverage.
2. Database integrity.
3. Authentication and authorization.
4. Subscription and payment lifecycle.
5. Exams, attempts, and grading.
6. Parent/student data isolation.
7. Teacher assignment scoping.
8. Security.
9. Performance.
10. Accessibility and responsive UI.
11. Backup and recovery.
12. Deployment and production readiness.