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.
Enterprise defaults: enterprise-phase-discovery.md · definition-of-done.md · mandatory-phase-artifacts.md · ADR-018 · ADR-019.

Document Loading

Follow Runtime Read Policy.

Do not start coding before Enterprise Phase Discovery, Business Analysis, and Architecture Validation complete.

Discovery Order (before coding)

1. Follow Runtime Read Policy
2. Inventory existing codebase, APIs, domain model, events, permissions, aggregates, tests, docs
3. Publish Discovery Record (baseline, target, gaps, promoted scope, exclusions)
4. Only then proceed to Domain Modeling / Implementation

Implementation Order

1. ADR/docs if a new decision is required
2. Domain modeling notes in the phase doc (aggregates, entities, DTOs) for Discovery-promoted scope
3. Models / migrations (entity-template.md)
4. Repositories with tenant/soft-delete/page/filter/sort/search (repository-template.md)
5. Specifications · Policies · Validators
6. Commands · Queries · Services + events (service-layer-template.md, event-template.md)
7. API routers + DTOs + OpenAPI (api-template.md); Health / Capabilities / Metrics / Permissions as required
8. Configuration, feature flags, seeds, background jobs when required
9. Provider adapters only if this service owns them
10. Frontend only if the phase explicitly includes UI
11. Keep diffs scoped to the phase — no drive-by refactors
12. Close every Discovery Missing→Implement gap — do not stop at CRUD

Documentation Order

1. Publish Discovery Record in the phase doc before claiming Implementation progress
2. Draft/update phase doc (Business Analysis + Domain Model) during or immediately after implementation
3. Update registries and manifests
4. Update reference catalogs when public surface changed
5. Update progress (completed) and next-steps (next milestone)
6. Fill handover (phase-handover.md) including Discovery summary + Enterprise Completeness + DoD
7. ADR index if a new ADR was added
8. Follow documentation-template.md

Validation Order

1. Automated tests (testing-template.md)
2. Self audit (Discovery gaps closed, scope creep, unfinished claimed work, layering, tenancy, secrets, mandatory artifacts)
3. Enterprise Completeness (enterprise-completeness.md)
4. Quality gates (quality-gates.md) including Discovery gate
5. Definition of Done (definition-of-done.md)
6. Link / cross-reference / manifest checks for doc changes
7. Repair loop until green — implement missing required work

Loop Behavior

• Follow development-loop.md stages strictly.
• On gate failure: fix root cause (implement missing artifact), re-validate, do not skip gates.
• On architecture conflict: stop coding; fix ADR/docs first.
• On boundary temptation (other service / future phase): stop; integrate or defer per boundary-rules.md.
• Prefer existing sibling service patterns (Accounting, CRM, Loyalty, Communication, platform services).

Completion Behavior

• Phase is complete only when Completion Rules in development-loop.md, Discovery gaps closed, and definition-of-done.md are satisfied.
• Print a concise completion summary for the user (include Discovery + completeness/DoD confirmation).
• 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.
• Discovery must inspect the real codebase/APIs/tests — do not Discovery from the phase brief alone.
• Run pytest for the touched service before claiming tests passed.
• For docs-only phases (like framework upgrades), run documentation/link/manifest validation instead of service pytest; still produce a Discovery Record against docs/manifests.
• Never modify unrelated completed business phases when upgrading the framework.

Related Documents

• Master Prompt
• Prompt Rules
• Enterprise Phase Discovery
• Definition of Done
• Quality Gates
• Developer Guide