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 and prompt-rules.md; load master-prompt.md; follow development-loop.md
Phase author	Copy phase-template.md; register in phase-manifest.yaml; deliver phase-handover.md
Service designer	Follow service-template.md; register in service-manifest.yaml
Reviewer	Validate against 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
2. This file (docs/ai-framework/README.md)
3. master-prompt.md
4. development-loop.md
5. prompt-rules.md · cursor-guidelines.md
6. quality-gates.md
7. Relevant templates (service / module / entity / repository / service-layer / api / event / testing / documentation)
8. phase-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.

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 passes and phase-handover.md deliverables are filled.

Relationship with Architecture

Architecture doc	Framework use
architecture/architecture.md	System map and permanent reading list
module-boundaries.md	Ownership checks before new modules/services
database-architecture.md	DB ownership / migration rules
multi-tenant-architecture.md	Tenant awareness gates
service-architecture.md	Layering (API → Service → Repository → Model)
event-driven-architecture.md	Event naming and outbox rules
ai-architecture.md	Product AI independence (distinct from this framework)
security-architecture.md · 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/.
• Framework adoption is recorded in ADR-013.
• 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.

Relationship with Development Standards

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

Framework templates extend these standards; they do not replace them. Prefer existing docs/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/
Phase detail docs	docs/*-phase-*.md or docs/phases/<Area>/
Phase status	progress.md · next-steps.md · roadmap.md
Phase registration	phase-manifest.yaml
Phase authoring template	phase-template.md
Phase exit package	phase-handover.md

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

Document Index

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

Phase AF Handover (Framework Creation)

Field	Value
Phase ID	ai-framework
Status	Complete
ADR	ADR-013
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 — Loyalty 7.1 using this framework

Related Documents

• Module Registry
• Provider Registry
• Glossary
• Reference
• Deployment
• ADR-013 — AI Development Framework