TorbatYar/docs/ai-framework/README.md

AI / Enterprise Development Framework

Permanent Enterprise Development Framework that every future AI-assisted (and human) implementation phase must follow.

This area does not implement business features. It defines how agents and humans plan, implement, validate, document, and complete phases at production quality by default without violating TorbatYar architecture.

Historical name: AI Development Framework (ADR-013). Enterprise completeness mandate: ADR-018. Folder path docs/ai-framework/ is retained for backward compatibility.

Purpose

1. Encode global project rules once (never duplicate them in phase prompts).
2. Make enterprise production readiness the default for every phase of every service.
3. Provide a mandatory Enterprise Phase Discovery, Definition of Done, Mandatory Phase Artifacts, Enterprise Completeness, and Boundary Rules.
4. Standardize the implementation lifecycle from Discovery to Completion.
5. Provide reusable templates for services, modules, entities, layers, APIs, events, tests, and docs.
6. Register phases and services in machine-readable manifests.
7. Enforce quality gates before any phase may be marked complete.

Single Source of Truth

Concern	Authority
What remains / what to execute next	docs/project-status.yaml — execution_priority + critical_path + deployment_readiness
Which documents to load	runtime-read-policy.md
Path resolution (active service)	project-index.yaml
How to implement any phase	This framework (docs/ai-framework/)
Technical architecture decisions	docs/architecture/ + ADRs
What was completed / what’s next (narrative)	progress.md / next-steps.md / roadmap.md
Module ownership	module-boundaries.md + module-registry.md

Phase prompts describe only the current phase. Permanent rules live here. Agents must not wait for a phase prompt to restate enterprise artifacts.

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, enterprise-phase-discovery.md, definition-of-done.md, enterprise-completeness.md

Reading Order

Every implementation phase starts here:

1. docs/project-status.yaml (first — execution dashboard)
2. docs/README.md
3. This file (docs/ai-framework/README.md)
4. master-prompt.md
5. runtime-read-policy.md · context-cache-policy.md · service-snapshot-policy.md
6. enterprise-phase-discovery.md · definition-of-done.md · mandatory-phase-artifacts.md · boundary-rules.md
7. development-loop.md
8. prompt-rules.md · cursor-guidelines.md
9. quality-gates.md · enterprise-completeness.md
10. Relevant templates (service / module / entity / repository / service-layer / api / event / testing / documentation)
11. phase-manifest.yaml · service-manifest.yaml · project-index.yaml
12. Active-service snapshot + latest handover only — then architecture/ADRs if referenced

Lifecycle

Canonical lifecycle: development-loop.md.

Enterprise Phase Discovery
  → Business Analysis
  → Architecture Validation
  → Domain Modeling (aggregates, entities, DTOs)
  → Implementation (Discovery gaps + mandatory artifacts)
  → Automated Testing
  → Self Audit
  → Documentation Update
  → Enterprise Completeness Verification
  → Quality Gates
  → Automatic Repair Loop (until green — implement missing required work)
  → Completion (DoD + handover + registry/progress updates)

No phase is complete until Discovery gaps are closed, definition-of-done.md is satisfied, every gate in quality-gates.md passes, enterprise-completeness.md is signed off, and phase-handover.md deliverables are filled.

CRUD is never sufficient.

Relationship with Architecture

Architecture doc	Framework use
architecture/architecture.md	System map and permanent reading list
module-boundaries.md	Ownership checks — mirrored in boundary-rules.md
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 implementation of any module.

Relationship with ADR

• Architecture decisions remain one decision per file under architecture/adr/.
• Framework adoption: ADR-013.
• Enterprise completeness mandate: ADR-018.
• Enterprise Phase Discovery mandate: ADR-019.
• 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 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/enterprise phases use the richer phase-template.md in this folder.

Document Index

Document	Responsibility
master-prompt.md	Global rules for every implementation
enterprise-phase-discovery.md	Mandatory pre-implementation discovery
definition-of-done.md	Mandatory phase Definition of Done
mandatory-phase-artifacts.md	Artifacts every phase includes by default
enterprise-completeness.md	Pre-close completeness verification
boundary-rules.md	Service/phase/integration hard boundaries
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 / commands / queries / policies / specs
api-template.md	REST / DTO / versioning / errors / OpenAPI
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-Discovery Handover (Enterprise Phase Discovery)

Field	Value
Phase ID	ai-framework-discovery
Status	Complete
ADR	ADR-019 (extends ADR-018)
Handover	phase-handover/phase-af-discovery.md
Reusable Components	Discovery procedure, Missing Capability Checklist, Discovery Record template, Discovery quality gate
Public APIs	N/A (documentation only)
Events	N/A
Extension Points	Extend Discovery checklist when new capability classes become permanent
Known Limitations	Does not retrofit completed business phases; docs-only Discovery still required
Migration Notes	N/A — docs-only
Dependencies	ADR-018 enterprise framework
Next Phase Entry	Resume business milestones per next-steps.md — Discovery runs automatically

Phase AF-Enterprise Handover (Framework Upgrade)

Field	Value
Phase ID	ai-framework-enterprise
Status	Complete
ADR	ADR-018 (extends ADR-013)
Handover	phase-handover/phase-af-enterprise.md
Reusable Components	DoD, mandatory artifacts, enterprise completeness, boundary rules + upgraded templates/gates/loop
Public APIs	N/A (documentation only)
Events	N/A
Extension Points	New permanent rules → extend framework docs + ADR if architectural
Known Limitations	Does not retrofit completed business phases/code; does not replace docs/templates/ short forms
Migration Notes	N/A — docs-only; backward-compatible paths
Dependencies	ADR-013 framework baseline
Next Phase Entry	Resume business milestones per next-steps.md — using this upgraded framework

Related Documents

• Module Registry
• Provider Registry
• Glossary
• Reference
• Deployment
• ADR-013 — AI Development Framework
• ADR-018 — Enterprise Completeness Mandate
• ADR-019 — Mandatory Enterprise Phase Discovery