TorbatYar/docs/ai-framework/cursor-guidelines.md

Cursor Guidelines

Cursor-specific workflow for TorbatYar implementation phases.

General prompt behavior: prompt-rules.md. Lifecycle: development-loop.md.

Reading Order

1. docs/README.md
2. AI Framework README
3. master-prompt.md
4. development-loop.md · quality-gates.md
5. prompt-rules.md (this workflow’s companion)
6. Phase brief + phase-manifest.yaml entry
7. service-manifest.yaml for touched services
8. docs/architecture/* and docs/architecture/adr/*
9. project-principles.md · coding-standards.md · testing-strategy.md
10. module-registry.md · provider-registry.md · glossary.md
11. Relevant phases/ and reference docs
12. Applicable templates (service/module/entity/repository/service-layer/api/event/testing/documentation)

Do not start coding before Architecture Validation completes.

Implementation Order

1. ADR/docs if a new decision is required
2. Models / migrations (entity-template.md)
3. Repositories (repository-template.md)
4. Validators + permissions
5. Services + events (service-layer-template.md, event-template.md)
6. API routers + DTOs (api-template.md)
7. Provider adapters only if this service owns them
8. Frontend only if the phase explicitly includes UI
9. Keep diffs scoped to the phase — no drive-by refactors

Documentation Order

1. Draft/update phase doc during or immediately after implementation
2. Update registries and manifests
3. Update reference catalogs when public surface changed
4. Update progress (completed) and next-steps (next milestone)
5. Fill handover (phase-handover.md)
6. ADR index if a new ADR was added
7. Follow documentation-template.md

Validation Order

1. Automated tests (testing-template.md)
2. Self audit (scope creep, unfinished claimed work, layering, tenancy, secrets)
3. Quality gates (quality-gates.md)
4. Link / cross-reference / manifest checks for doc changes
5. Repair loop until green

Loop Behavior

• Follow development-loop.md stages strictly.
• On gate failure: fix root cause, re-validate, do not skip gates.
• On architecture conflict: stop coding; fix ADR/docs first.
• Prefer existing sibling service patterns (Accounting, CRM, Loyalty, Communication).

Completion Behavior

• Phase is complete only when Completion Rules in development-loop.md are satisfied.
• Print a concise completion summary for the user.
• Stop — do not begin the next phase unless the user explicitly requests it.
• Do not commit unless the user asks (project git norms).

Cursor Tooling Notes

• Use the repo’s docs and code as source of truth; do not invent registries.
• Run pytest for the touched service before claiming tests passed.
• For docs-only phases (like framework creation), run documentation/link/manifest validation instead of service pytest.

Related Documents

• Master Prompt
• Prompt Rules
• Quality Gates
• Developer Guide