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](../architecture/adr/ADR-013.md)). Enterprise completeness mandate: [ADR-018](../architecture/adr/ADR-018.md). 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](enterprise-phase-discovery.md), [Definition of Done](definition-of-done.md), [Mandatory Phase Artifacts](mandatory-phase-artifacts.md), [Enterprise Completeness](enterprise-completeness.md), and [Boundary Rules](boundary-rules.md).
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`](../project-status.yaml) — `execution_priority` + `critical_path` + `deployment_readiness` |
| Which documents to load | [runtime-read-policy.md](runtime-read-policy.md) |
| Path resolution (active service) | [project-index.yaml](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](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), [enterprise-phase-discovery.md](enterprise-phase-discovery.md), [definition-of-done.md](definition-of-done.md), [enterprise-completeness.md](enterprise-completeness.md) |

## Reading Order

Every implementation phase starts here:

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

## Lifecycle

Canonical lifecycle: [development-loop.md](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](definition-of-done.md) is satisfied, every gate in [quality-gates.md](quality-gates.md) passes, [enterprise-completeness.md](enterprise-completeness.md) is signed off, and [phase-handover.md](phase-handover.md) deliverables are filled.

**CRUD is never sufficient.**

## 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 — mirrored in [boundary-rules.md](boundary-rules.md) |
| [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 implementation of any module.

## Relationship with ADR

- Architecture decisions remain one decision per file under [architecture/adr/](../architecture/adr/).
- Framework adoption: [ADR-013](../architecture/adr/ADR-013.md).
- Enterprise completeness mandate: [ADR-018](../architecture/adr/ADR-018.md).
- Enterprise Phase Discovery mandate: [ADR-019](../architecture/adr/ADR-019.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 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/enterprise 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 implementation |
| [enterprise-phase-discovery.md](enterprise-phase-discovery.md) | Mandatory pre-implementation discovery |
| [definition-of-done.md](definition-of-done.md) | Mandatory phase Definition of Done |
| [mandatory-phase-artifacts.md](mandatory-phase-artifacts.md) | Artifacts every phase includes by default |
| [enterprise-completeness.md](enterprise-completeness.md) | Pre-close completeness verification |
| [boundary-rules.md](boundary-rules.md) | Service/phase/integration hard boundaries |
| [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 / commands / queries / policies / specs |
| [api-template.md](api-template.md) | REST / DTO / versioning / errors / OpenAPI |
| [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-Discovery Handover (Enterprise Phase Discovery)

| Field | Value |
| --- | --- |
| Phase ID | `ai-framework-discovery` |
| Status | Complete |
| ADR | [ADR-019](../architecture/adr/ADR-019.md) (extends [ADR-018](../architecture/adr/ADR-018.md)) |
| Handover | [phase-handover/phase-af-discovery.md](../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](../next-steps.md) — Discovery runs automatically |

## Phase AF-Enterprise Handover (Framework Upgrade)

| Field | Value |
| --- | --- |
| Phase ID | `ai-framework-enterprise` |
| Status | Complete |
| ADR | [ADR-018](../architecture/adr/ADR-018.md) (extends [ADR-013](../architecture/adr/ADR-013.md)) |
| Handover | [phase-handover/phase-af-enterprise.md](../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](../next-steps.md) — using this upgraded 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)
- [ADR-018 — Enterprise Completeness Mandate](../architecture/adr/ADR-018.md)
- [ADR-019 — Mandatory Enterprise Phase Discovery](../architecture/adr/ADR-019.md)