# Cursor Guidelines

Cursor-specific workflow for TorbatYar implementation phases.

General prompt behavior: [prompt-rules.md](prompt-rules.md). Lifecycle: [development-loop.md](development-loop.md).

## Reading Order

1. [docs/README.md](../README.md)
2. [AI Framework README](README.md)
3. [master-prompt.md](master-prompt.md)
4. [development-loop.md](development-loop.md) · [quality-gates.md](quality-gates.md)
5. [prompt-rules.md](prompt-rules.md) (this workflow’s companion)
6. Phase brief + [phase-manifest.yaml](phase-manifest.yaml) entry
7. [service-manifest.yaml](service-manifest.yaml) for touched services
8. `docs/architecture/*` and `docs/architecture/adr/*`
9. [project-principles.md](../development/project-principles.md) · [coding-standards.md](../development/coding-standards.md) · [testing-strategy.md](../development/testing-strategy.md)
10. [module-registry.md](../module-registry.md) · [provider-registry.md](../provider-registry.md) · [glossary.md](../glossary.md)
11. Relevant [phases/](../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](entity-template.md))
3. Repositories ([repository-template.md](repository-template.md))
4. Validators + permissions
5. Services + events ([service-layer-template.md](service-layer-template.md), [event-template.md](event-template.md))
6. API routers + DTOs ([api-template.md](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](phase-handover.md))
6. ADR index if a new ADR was added
7. Follow [documentation-template.md](documentation-template.md)

## Validation Order

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

## Loop Behavior

- Follow [development-loop.md](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](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](../development/branching-strategy.md)).

## 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](master-prompt.md)
- [Prompt Rules](prompt-rules.md)
- [Quality Gates](quality-gates.md)
- [Developer Guide](../development/developer-guide.md)