# ADR-013: Permanent AI Development Framework

| Field | Value |
| --- | --- |
| Status | Accepted |
| Date | 2026-07-24 |
| Deciders | Platform Architecture |
| Supersedes | — |
| Superseded by | — |

## Context

TorbatYar is implemented across many phases and services. AI-assisted implementation without a permanent process framework risks recreating completed work, violating module boundaries, skipping documentation gates, and drifting from ADRs.

Product AI (`ai_assistant`) is a business capability. Implementation process for any module must be governed separately.

## Decision

1. Adopt a permanent **AI Development Framework** under `docs/ai-framework/`.
2. Every future implementation phase must follow the framework reading order, development loop, prompt rules, Cursor guidelines, templates, manifests, and quality gates.
3. Phase prompts describe **only** the current phase; permanent rules live in the framework.
4. No phase is complete until quality gates pass and phase-handover deliverables are filled.
5. Machine-readable registration uses `phase-manifest.yaml` and `service-manifest.yaml`.
6. This ADR does **not** implement product AI features.

## Consequences

### Positive

- Consistent AI/human implementation lifecycle
- Clear separation between process framework and product AI
- Enforceable completion gates and handover continuity

### Negative

- Additional documentation discipline required before coding

### Neutral

- Existing architecture ADRs remain authoritative for technical decisions

## Alternatives Considered

1. Per-phase duplicated rules in every prompt — rejected (drift, inconsistency)
2. Relying only on agent memory — rejected (not auditable)
3. Treating product AI architecture as the implementation process — rejected (different concern)

## Related Documents

- [AI Development Framework](../../ai-framework/README.md)
- [Master Prompt](../../ai-framework/master-prompt.md)
- [Development Loop](../../ai-framework/development-loop.md)
- [Quality Gates](../../ai-framework/quality-gates.md)
- [Phase Manifest](../../ai-framework/phase-manifest.yaml)
- [Project Principles](../../development/project-principles.md)