TorbatYar/docs/ai-framework/development-loop.md

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, AI Framework README, 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).
4. Confirm Objective, Scope, Out of Scope, Dependencies, and Required Services from 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, database-architecture.md, multi-tenant-architecture.md.
2. Confirm Database-per-Service, tenancy, eventing, and FE/BE separation.
3. Confirm service vs module decision (service-template.md vs 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 implementation order.
2. Models / entities per entity-template.md.
3. Repositories per repository-template.md.
4. Services per service-layer-template.md.
5. Validators, permissions, events per event-template.md.
6. APIs / DTOs per 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 and 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.
2. Update phase doc, progress, next-steps, module registry, provider registry (if needed), reference contracts/events/APIs as applicable.
3. Update phase-manifest.yaml / service-manifest.yaml status and versions.
4. Fill 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:

• 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).
6. progress.md records completion; next-steps.md points to the next milestone.
7. No TODO remains for claimed deliverables.
8. Final verification checklist in docs/README.md Phase Completion Gate is satisfied.

After completion: stop. Do not start the next phase unless explicitly requested.

Related Documents

• Master Prompt
• Quality Gates
• Phase Handover
• Cursor Guidelines
• Project Principles