e41ecfad4c
Include Loyalty/Communication/Sports Center backends and registry updates alongside production nginx and compose wiring. Co-authored-by: Cursor <cursoragent@cursor.com>
112 lines
5.2 KiB
Markdown
112 lines
5.2 KiB
Markdown
# Development Loop
|
||
|
||
Permanent implementation lifecycle for every TorbatYar phase.
|
||
|
||
Agents and humans follow these stages in order. After Quality Gates fail, enter the Automatic Repair Loop until all gates pass, then complete.
|
||
|
||
## 1. Requirements Analysis
|
||
|
||
1. Read [docs/README.md](../README.md), [AI Framework README](README.md), [master-prompt.md](master-prompt.md).
|
||
2. Read architecture (`docs/architecture/*`, `docs/architecture/adr/*`), development standards, registries, glossary.
|
||
3. Read the phase brief (or create from [phase-template.md](phase-template.md)).
|
||
4. Confirm Objective, Scope, Out of Scope, Dependencies, and Required Services from [phase-manifest.yaml](phase-manifest.yaml).
|
||
5. List aggregates, APIs, events, permissions, and docs that must change.
|
||
6. Stop if requirements conflict with ADRs or module boundaries — resolve via ADR/docs first.
|
||
|
||
**Exit:** Written understanding of in-scope deliverables and explicit non-goals.
|
||
|
||
## 2. Architecture Validation
|
||
|
||
1. Validate against [module-boundaries.md](../architecture/module-boundaries.md), [database-architecture.md](../architecture/database-architecture.md), [multi-tenant-architecture.md](../architecture/multi-tenant-architecture.md).
|
||
2. Confirm Database-per-Service, tenancy, eventing, and FE/BE separation.
|
||
3. Confirm service vs module decision ([service-template.md](service-template.md) vs [module-template.md](module-template.md)).
|
||
4. Identify required ADRs; create Proposed/Accepted ADR if a new decision is introduced.
|
||
5. Confirm no ownership theft (e.g. CRM must not own Loyalty or Communication).
|
||
|
||
**Exit:** Architecture checklist green or ADR/docs updated to resolve conflicts.
|
||
|
||
## 3. Implementation
|
||
|
||
1. Follow [cursor-guidelines.md](cursor-guidelines.md) implementation order.
|
||
2. Models / entities per [entity-template.md](entity-template.md).
|
||
3. Repositories per [repository-template.md](repository-template.md).
|
||
4. Services per [service-layer-template.md](service-layer-template.md).
|
||
5. Validators, permissions, events per [event-template.md](event-template.md).
|
||
6. APIs / DTOs per [api-template.md](api-template.md).
|
||
7. Migrations owned by the service database only.
|
||
8. Do not implement out-of-scope features.
|
||
|
||
**Exit:** Code matches phase scope; no unrelated service edits.
|
||
|
||
## 4. Automated Testing
|
||
|
||
1. Apply [testing-template.md](testing-template.md) and [testing-strategy.md](../development/testing-strategy.md).
|
||
2. Run the service’s pytest (and relevant sibling suites if contracts changed).
|
||
3. Include tenant isolation negatives for new tenant-scoped APIs.
|
||
4. Include permission, migration, architecture/boundary, and docs validation tests when the service pattern requires them.
|
||
|
||
**Exit:** All required tests pass locally (or in CI for the phase).
|
||
|
||
## 5. Self Audit
|
||
|
||
1. Re-read Scope / Out of Scope — reject scope creep.
|
||
2. Search for TODO/FIXME in touched paths related to claimed deliverables.
|
||
3. Verify layering (no business logic in routers/repos).
|
||
4. Verify no cross-DB access or foreign model imports.
|
||
5. Verify secrets/brand not hardcoded.
|
||
6. Verify audit/events for state-changing business actions.
|
||
|
||
**Exit:** Self-audit notes with no open blockers.
|
||
|
||
## 6. Documentation Update
|
||
|
||
1. Follow [documentation-template.md](documentation-template.md).
|
||
2. Update phase doc, progress, next-steps, module registry, provider registry (if needed), reference contracts/events/APIs as applicable.
|
||
3. Update [phase-manifest.yaml](phase-manifest.yaml) / [service-manifest.yaml](service-manifest.yaml) status and versions.
|
||
4. Fill [phase-handover.md](phase-handover.md) sections for the phase (or phase-specific handover section in the phase doc).
|
||
|
||
**Exit:** Docs consistent with code; cross-links valid.
|
||
|
||
## 7. Quality Gates
|
||
|
||
Run every gate in [quality-gates.md](quality-gates.md):
|
||
|
||
- Architecture · Security · Performance · Testing · Documentation · Migration · Backward Compatibility · Tenant Isolation
|
||
|
||
**Exit:** All gates Pass, or Fail with a concrete defect list.
|
||
|
||
## 8. Automatic Repair Loop
|
||
|
||
While any gate fails:
|
||
|
||
1. Classify defect (architecture, security, test, docs, link, tenancy, migration, compatibility).
|
||
2. Fix the smallest correct change (prefer docs/ADR first when rules conflict).
|
||
3. Re-run the failed gate and dependent gates.
|
||
4. Do not mark the phase complete while any gate fails.
|
||
5. Do not weaken gates to force completion.
|
||
|
||
**Exit:** All gates Pass.
|
||
|
||
## 9. Completion Rules
|
||
|
||
A phase may be marked complete only when:
|
||
|
||
1. Code and tests for in-scope work are done and green.
|
||
2. Documentation and registries are updated.
|
||
3. ADR updated/created if required.
|
||
4. Quality gates all Pass.
|
||
5. Handover package is complete ([phase-handover.md](phase-handover.md)).
|
||
6. [progress.md](../progress.md) records completion; [next-steps.md](../next-steps.md) points to the next milestone.
|
||
7. No TODO remains for claimed deliverables.
|
||
8. Final verification checklist in [docs/README.md](../README.md) Phase Completion Gate is satisfied.
|
||
|
||
After completion: stop. Do not start the next phase unless explicitly requested.
|
||
|
||
## Related Documents
|
||
|
||
- [Master Prompt](master-prompt.md)
|
||
- [Quality Gates](quality-gates.md)
|
||
- [Phase Handover](phase-handover.md)
|
||
- [Cursor Guidelines](cursor-guidelines.md)
|
||
- [Project Principles](../development/project-principles.md)
|