TorbatYar/docs/ai-framework/README.md

# AI Development Framework

Permanent framework that every future AI-assisted implementation phase must follow.

This area does **not** implement business features. It defines how AI agents and humans plan, implement, validate, document, and complete phases without violating TorbatYar architecture.

## Purpose

1. Encode global project rules once (never duplicate them in phase prompts).
2. Standardize the implementation lifecycle from requirements to completion.
3. Provide reusable templates for services, modules, entities, layers, APIs, events, tests, and docs.
4. Register phases and services in machine-readable manifests.
5. Enforce quality gates before any phase may be marked complete.

## Usage

| Audience | How to use |
| --- | --- |
| AI agent (Cursor / other) | Read [cursor-guidelines.md](cursor-guidelines.md) and [prompt-rules.md](prompt-rules.md); load [master-prompt.md](master-prompt.md); follow [development-loop.md](development-loop.md) |
| Phase author | Copy [phase-template.md](phase-template.md); register in [phase-manifest.yaml](phase-manifest.yaml); deliver [phase-handover.md](phase-handover.md) |
| Service designer | Follow [service-template.md](service-template.md); register in [service-manifest.yaml](service-manifest.yaml) |
| Reviewer | Validate against [quality-gates.md](quality-gates.md) |

Phase prompts must describe **only** the current phase. Permanent rules live here.

## Reading Order

Every implementation phase starts here:

1. [docs/README.md](../README.md)
2. This file (`docs/ai-framework/README.md`)
3. [master-prompt.md](master-prompt.md)
4. [development-loop.md](development-loop.md)
5. [prompt-rules.md](prompt-rules.md) · [cursor-guidelines.md](cursor-guidelines.md)
6. [quality-gates.md](quality-gates.md)
7. Relevant templates (service / module / entity / repository / service-layer / api / event / testing / documentation)
8. [phase-manifest.yaml](phase-manifest.yaml) · [service-manifest.yaml](service-manifest.yaml)
9. Then architecture, ADRs, development standards, registries, glossary, and the phase’s own docs

## Lifecycle

Canonical lifecycle: [development-loop.md](development-loop.md).

```
Requirements Analysis
  → Architecture Validation
  → Implementation
  → Automated Testing
  → Self Audit
  → Documentation Update
  → Quality Gates
  → Automatic Repair Loop (until green)
  → Completion (handover + registry/progress updates)
```

No phase is complete until every gate in [quality-gates.md](quality-gates.md) passes and [phase-handover.md](phase-handover.md) deliverables are filled.

## Relationship with Architecture

| Architecture doc | Framework use |
| --- | --- |
| [architecture/architecture.md](../architecture/architecture.md) | System map and permanent reading list |
| [module-boundaries.md](../architecture/module-boundaries.md) | Ownership checks before new modules/services |
| [database-architecture.md](../architecture/database-architecture.md) | DB ownership / migration rules |
| [multi-tenant-architecture.md](../architecture/multi-tenant-architecture.md) | Tenant awareness gates |
| [service-architecture.md](../architecture/service-architecture.md) | Layering (API → Service → Repository → Model) |
| [event-driven-architecture.md](../architecture/event-driven-architecture.md) | Event naming and outbox rules |
| [ai-architecture.md](../architecture/ai-architecture.md) | Product AI independence (distinct from this framework) |
| [security-architecture.md](../architecture/security-architecture.md) · [authorization-architecture.md](../architecture/authorization-architecture.md) | Security / permission gates |

**Distinction:** Product AI (`ai_assistant` / AI phase area) is a business capability. This framework is **development process** documentation for AI-assisted implementation of any module.

## Relationship with ADR

- Architecture decisions remain one decision per file under [architecture/adr/](../architecture/adr/).
- Framework adoption is recorded in [ADR-013](../architecture/adr/ADR-013.md).
- If a phase introduces a new architectural decision, create an ADR **before** conflicting code.
- Never overwrite an accepted ADR — supersede it.
- Template: [templates/adr-template.md](../templates/adr-template.md).

## Relationship with Development Standards

| Standard | Framework use |
| --- | --- |
| [project-principles.md](../development/project-principles.md) | Non-negotiable principles mirrored in master-prompt |
| [coding-standards.md](../development/coding-standards.md) | Coding rules for implementation |
| [testing-strategy.md](../development/testing-strategy.md) | Baseline for [testing-template.md](testing-template.md) |
| [branching-strategy.md](../development/branching-strategy.md) · [release-strategy.md](../development/release-strategy.md) | Delivery hygiene |
| [developer-guide.md](../development/developer-guide.md) | How to run services locally |

Framework templates **extend** these standards; they do not replace them. Prefer existing [docs/templates/](../templates/) for registry-style docs; use `docs/ai-framework/*-template.md` for AI implementation phases.

## Relationship with Phase Documents

| Phase artifact | Location |
| --- | --- |
| Phase area overviews | [docs/phases/](../phases/) |
| Phase detail docs | `docs/*-phase-*.md` or `docs/phases/<Area>/` |
| Phase status | [progress.md](../progress.md) · [next-steps.md](../next-steps.md) · [roadmap.md](../roadmap.md) |
| Phase registration | [phase-manifest.yaml](phase-manifest.yaml) |
| Phase authoring template | [phase-template.md](phase-template.md) |
| Phase exit package | [phase-handover.md](phase-handover.md) |

Legacy phase template (registry-oriented): [templates/phase-template.md](../templates/phase-template.md). AI phases use the richer [phase-template.md](phase-template.md) in this folder.

## Document Index

| Document | Responsibility |
| --- | --- |
| [master-prompt.md](master-prompt.md) | Global rules for every AI implementation |
| [development-loop.md](development-loop.md) | Permanent implementation lifecycle |
| [phase-handover.md](phase-handover.md) | Required exit deliverables |
| [phase-template.md](phase-template.md) | Reusable phase brief |
| [service-template.md](service-template.md) | New independent service design |
| [module-template.md](module-template.md) | Module inside an existing service |
| [entity-template.md](entity-template.md) | Entity / schema standards |
| [repository-template.md](repository-template.md) | Repository standards |
| [service-layer-template.md](service-layer-template.md) | Service layer standards |
| [api-template.md](api-template.md) | REST / DTO / versioning / errors |
| [event-template.md](event-template.md) | Domain & integration events |
| [testing-template.md](testing-template.md) | Mandatory tests |
| [documentation-template.md](documentation-template.md) | Post-phase documentation updates |
| [quality-gates.md](quality-gates.md) | Mandatory quality gates |
| [phase-manifest.yaml](phase-manifest.yaml) | Phase registry |
| [service-manifest.yaml](service-manifest.yaml) | Service registry |
| [prompt-rules.md](prompt-rules.md) | How future phase prompts must behave |
| [cursor-guidelines.md](cursor-guidelines.md) | Cursor-specific workflow |

## Phase AF Handover (Framework Creation)

| Field | Value |
| --- | --- |
| Phase ID | `ai-framework` |
| Status | Complete |
| ADR | [ADR-013](../architecture/adr/ADR-013.md) |
| Reusable Components | All templates + manifests + loop/gates under this folder |
| Public APIs | N/A (documentation only) |
| Events | N/A |
| Extension Points | New permanent rules → extend framework docs; new phases → phase-template + manifests |
| Known Limitations | Does not implement product AI Assistant; does not replace `docs/templates/` short forms |
| Migration Notes | N/A |
| Dependencies | Existing documentation architecture (Phase D) |
| Next Phase Entry | [next-steps.md](../next-steps.md) — Loyalty 7.1 using this framework |

## Related Documents

- [Module Registry](../module-registry.md)
- [Provider Registry](../provider-registry.md)
- [Glossary](../glossary.md)
- [Reference](../reference/)
- [Deployment](../deployment/)
- [ADR-013 — AI Development Framework](../architecture/adr/ADR-013.md)