# Implementation Roadmap

## Purpose

This roadmap turns the current starter agent into the planned marketing services platform through incremental, testable phases.

## Current Starting Point

The repository currently has:

- a basic Microsoft 365 custom engine agent surface
- a single inline system prompt in `src/agent.ts`
- transient in-memory storage
- Azure OpenAI configuration only

That means the delivery plan should preserve the working chat entrypoint while replacing the single-step request handling with layered orchestration and durable context handling.

## Phase 1: Externalize Prompting And Configuration

### Objectives

- move prompt content out of inline code
- introduce prompt package concepts without changing the chat surface
- prepare the codebase for modular services

### Deliverables

- prompt asset loading strategy
- prompt metadata conventions
- configuration expansion for storage and integration settings
- initial directory split for orchestration, prompts, and context services

### Suggested Repo Changes

- keep `src/index.ts` as the entrypoint
- reduce `src/agent.ts` to message handling and orchestration delegation
- add prompt and orchestration modules under `src/`

## Phase 2: Add Identity And Tenant Resolution

### Objectives

- resolve user identity through Microsoft Graph
- map users to tenant, brand, business unit, and role
- enforce scope before retrieval or tool access

### Deliverables

- identity resolver service
- tenant and role mapping service
- access profile model
- fail-closed handling for ambiguous scope

## Phase 3: Add Retrieval, Caching, And Document Sync

### Objectives

- ingest system and customer documents from Google Drive and Google Docs
- normalize and cache source material
- make retrieval low-latency and approval-aware

### Deliverables

- sync jobs for system and customer source collections
- normalized cache format
- retrieval index and scope filtering
- provenance metadata recorded for prompt assembly

## Phase 4: Add Orchestration And Model Routing

### Objectives

- classify requests by service type
- route to the right model and tool policy
- assemble prompt packages from system, customer, and session context

### Deliverables

- request classifier
- model router
- tool policy layer
- prompt assembler
- audit logging for orchestration decisions

## Phase 5: Add Approval Workflows And Generated Artifact Handling

### Objectives

- separate drafts from approved reusable assets
- support approval transitions inside or adjacent to chat workflows
- preserve provenance for all outputs

### Deliverables

- generated artifact store
- approval event model
- promotion flow from generated to approved
- retirement handling for outdated assets

## Phase 6: Add Multimodal Service Paths

### Objectives

- extend beyond text chat into research, image, creative brief, and video-oriented flows
- apply task-specific tool and model policies

### Deliverables

- service-specific orchestration strategies
- multimodal prompt templates
- capability-aware routing rules
- output review and handoff patterns

## Phase 7: Production Hardening

### Objectives

- improve observability, auditability, and reliability
- support internal and customer rollout with clear governance

### Deliverables

- monitoring and alerting
- admin operations for prompt and source refresh
- access review procedures
- release checklist and operational runbook

## Recommended Build Order For This Repository

1. keep the existing Teams and Copilot surface intact
2. introduce modules behind the current `src/agent.ts` handler
3. replace `MemoryStorage` with durable state and metadata storage
4. add identity and tenant gating before retrieval
5. add system and customer retrieval
6. layer in orchestration and approval workflows
7. add multimodal capabilities after governance is stable

## Success Criteria By Milestone

### Milestone A

The agent still responds in chat, but prompt assets are externalized and request handling is modular.

### Milestone B

Users are mapped to tenant and role, and retrieval is limited to authorized context.

### Milestone C

System and customer documents are cached and retrieved with provenance.

### Milestone D

Generated outputs can move through approval states without contaminating long-term memory.

### Milestone E

The platform supports multiple marketing service modes through a shared orchestration core.