playbook-migration-cleanup.md12.6 KBView on GitHub # Playbook Migration — Complete Cleanup Guide
This document is the authoritative checklist for fully removing the old `aop_agents`-based execution system and replacing it with the playbook system. Organized by phase, with exact file paths and line references.
---
## Phase 1: Remove old execution fallbacks (safe to do once all AOPs have playbooks)
These are the `hasPlaybook` gates and legacy branches that run the old pipeline when no playbook is found. Removing them makes the playbook path unconditional.
### 1.1 `pre-execution-setup.ts` — remove legacy fallback
**File**: `apps/server/src/mastra/workflows/event-execution/pre-execution-setup.ts`
Currently: tries `getPlaybookSection`, if error falls back to legacy path, sets `hasPlaybook: false` and `playbookSection: undefined`.
**Remove**: the entire `catch` block around the playbook section call and any code paths that set `hasPlaybook: false`. After removal, if no playbook exists, the workflow should skip execution entirely (treat the AOP as not configured) rather than falling back.
### 1.2 `on-event-agent-execution-workflow.ts` — remove legacy branch
**File**: `apps/server/src/mastra/workflows/event-execution/on-event-agent-execution-workflow.ts`
Lines ~641-678: ternary that constructs either `<playbook_section>` (playbook path) or `<pipeline_agents>` + `<automation_agents>` JSON blocks (legacy path).
**Remove**: the entire legacy branch — everything in the `else` clause that constructs `<pipeline_agents>` and `<automation_agents>`. After removal, the prompt always uses `<playbook_section>`.
Also lines ~416-467: fetches `pipelineAgents` using `getEventPipelineAgents` / instructions preview loop.
**Remove**: the entire pipeline agent fetch block — it only feeds the legacy `<pipeline_agents>` JSON.
### 1.3 `on-event-orchestrator-agent.ts` — remove legacy orchestrator instructions
**File**: `apps/server/src/mastra/agents/on-event-orchestrator-agent.ts`
Currently has conditional sections in `orchestratorInstructions` for the old step-by-step pipeline (Step 1: CRM Updater, Step 2: Overview Agent, etc.) that only apply when `<pipeline_agents>` is present.
**Remove**: the legacy pipeline step instructions from the orchestrator system prompt. Keep only the `<playbook_mode>` instructions (now loaded from the `playbook-execution` skill).
Also remove `run-automation-agent` from all 4 orchestrator variants' tool registration (lines ~323, 348, 367).
### 1.4 Remove `run-automation-agent` tool
**File**: `apps/server/src/mastra/tools/event-execution/orchestrator-dispatch-tools.ts`
Lines ~905-997: the `runAutomationAgentTool` definition (~93 lines). Completely superseded by `runSubagentTool`.
**Remove**: the tool definition and all imports/exports for it.
### 1.5 Remove pipeline agent service functions
**File**: `apps/server/src/services/aop/aop-agents.ts`
Functions to remove once no longer called:
- `getEventPipelineAgents(db, aopId)` — fetches `event_occurred` agents for the pipeline
- `getEnabledEventAgentsForAop(db, aopId, triggerType?)` — fetches enabled agents by trigger
Keep: `getAgentsForAop` (still used by the playground Agents tab UI), `seedSystemDefaultAgents` (still needed for new account setup until fully deprecated), `MEETING_PREP_INSTRUCTIONS`, `DAILY_AGENDA_PROMPT`.
---
## Phase 2: Remove legacy tools superseded by `run-subagent`
These tools remain temporarily because non-playbook AOPs still use them. Once all AOPs have playbooks, they can be removed.
### 2.1 `run-crm-updater` (~346 lines in orchestrator-dispatch-tools.ts)
Currently: the `run-crm-updater` tool calls `runCrmUpdaterTool` which reads `crm-updater.md` from the subagents folder (via `readSystemSubagentInstructions`) and runs the CRM update logic.
**Superseded by**: `run-subagent('@subagents/crm-updater', reasoning)` which reads the same file and runs via `runAgent`.
**Remove after**: all AOPs have playbooks with `@subagents/crm-updater:` in their trigger blocks.
### 2.2 `run-post-event-executor` (~320 lines)
Currently: runs the post-event task execution (email drafting, Slack messages). Has hardcoded template reading logic and special email-drafting skill loading.
**Superseded by**: `run-subagent('@subagents/post-event-executor', reasoning)` — or removed entirely if post-event drafting is moved inline to the orchestrator's stage instructions.
**Note**: The `run-post-event-executor` tool has significant logic for reading `email_drafting` skill config. This logic needs to be replicated in the `post-event-executor` subagent file's instructions before the tool can be removed.
### 2.3 `run-deal-overview` (~158 lines)
Currently: updates the deal overview document. Has its own template/structure logic.
**Superseded by**: can be a custom subagent file, or the overview agent can be built into the stage's `[on:meeting]` block directly.
### 2.4 `update-next-steps-and-tasks` (~782 lines in updateNextStepsAndTasksTool.ts)
Currently: the `run-update-next-steps-and-tasks` tool. Complex tool with synthetic event creation, task triage, and next-step management.
**Superseded by**: `run-subagent('@subagents/next-steps', reasoning)` — but the subagent file currently has a simple stub. Before removing the tool, the full task triage logic (sell-between cadence, exponential back-off, suppression rules) needs to be captured either in the `next-steps.md` subagent instructions or handled via the `task-management` skill loaded by the subagent.
**Important**: This is the most complex tool to remove. The current `next-steps.md` stub delegates to the `task-management` skill, which handles the execution — but the sell-between email cadence and specific CRM-state-based suppression rules from `updateNextStepsAndTasksTool.ts` must be moved to the subagent's `fill_instructions` or a dedicated resource file.
---
## Phase 3: Remove legacy data model (after Phase 1 + 2 complete)
### 3.1 `aop_agents` table
The central table storing agent configurations. Once the playbook system is the sole execution path and no UI reads from it, this table can be dropped.
**Dependent code to remove first**:
- `apps/server/src/trpc/routes/aop-agents.ts` — entire tRPC router
- Playground Agents tab (`AgentsEditor.tsx`) — replace with playbook editor for agent config
- `apps/server/src/mastra/workflows/event-execution/on-event-agent-execution-workflow.ts` — pipeline agent fetch calls
- `apps/server/src/services/aop/aop-agents.ts` — most functions (keep `MEETING_PREP_INSTRUCTIONS`, `DAILY_AGENDA_PROMPT` as they're used by seed)
- Cron job in `cron-task-registry.ts` that reads `aop_agents` for cron/before-meeting agents
- `process-before-meeting-scheduling.ts` — legacy agent scheduling path
**DB migration**: `DROP TABLE aop_agents;`
### 3.2 `aop_skills` table
Stores legacy skill content (overall_goal, email_drafting, coaching_framework, etc.). Now superseded by playbook resource files.
**Dependent code to remove**:
- `apps/server/src/services/aop/skills-docs.ts` — entire file (reads from this table)
- `apps/server/src/services/aop/aop-context.ts` — `resolveAlwaysIncludeSkills`, `getSkillConfigs` (these read from skill docs for the legacy execution path)
- `apps/server/src/trpc/routes/aop.ts` — skill-related endpoints
- Playground Skills tab (if it exists)
**DB migration**: `DROP TABLE aop_skills;`
### 3.3 `loadAgentOperatingProcedureDetailsTool` file
**File**: `apps/server/src/mastra/tools/aop/loadAgentOperatingProcedureDetailsTool.ts`
Still imported by `automation-agent.ts` and `task-triaging.ts` skill. Once those are updated to use `list-aops` + playbook reads:
- Remove from `automation-agent.ts` tools
- Remove from `task-triaging.ts` skill tools
- Delete the file
### 3.4 Legacy agent instruction docs path
**File**: `apps/server/src/services/aop/agent-instructions-docs.ts`
Used by `upsertAgentInstructions` (called by `runSubagentTool` to write instructions before running an agent). This is a workaround — `runSubagentTool` writes the subagent's instructions to the legacy path so `runAgent` can find them.
**Remove after**: `runAgent` is updated to accept instructions directly instead of reading from Cedar Docs by convention path.
---
## Phase 4: Remove legacy context resolution (parallel with Phase 3)
### 4.1 `resolveAlwaysIncludeSkills` in `aop-context.ts`
Currently: reads `overall_goal`, `company_sop`, `coaching_framework` from Cedar Docs skill paths and concatenates them as always-loaded context.
**Superseded by**: playbook `## The agent sees these every time` section with `@resources/overall-goal`, `@resources/coaching-framework`, `@org/resources/company-sop` refs.
**Remove**: `resolveAlwaysIncludeSkills`, `getSkillConfigs`, `resolveSkillSection` from `aop-context.ts`.
### 4.2 Legacy skill resolution in pre-execution-setup
**File**: `apps/server/src/mastra/workflows/event-execution/pre-execution-setup.ts`
The `PreExecutionSetupResult` currently includes `alwaysIncludeSkills` (loaded from the legacy skill table). Once the playbook `<always_loaded_context>` block handles this, remove the skill loading from pre-execution-setup.
### 4.3 Prompt field-mapping in `user-context.ts`
The user context formatter currently includes legacy AOP fields (docTemplate, customFieldSummary, etc.) that are no longer needed once the playbook is the sole config surface. Slim this down to just the identifying fields (name, id) that the orchestrator still needs.
---
## Phase 5: AOP editor UI cleanup
Once the playbook handles all behavioral config, several AOP editor tabs become redundant or need redesign:
| Tab | Status | Action |
|---|---|---|
| **Playbook** | ✅ New | Keep — primary config surface |
| **Agents** | ❌ Legacy | Remove once `aop_agents` table gone; agent config lives in playbook `subagents/` folder |
| **Conversation Fields** | ⚠️ Partial | Keep the field definitions UI; consider moving to playbook `## Conversation fields` section |
| **Integrations** | ⚠️ Partial | CRM field mappings → consider org playbook section; connection credentials stay |
| **Intelligence** | ⚠️ Partial | Stays as structured editor for now |
| **Settings** | ✅ Keep | User preferences, not AOP behavioral config |
| **Procedure** | ⚠️ Partial | Selection procedure → now in playbook `## Selection procedure`; scope config stays |
---
## Config still NOT in the playbook (decision pending)
### Conversation Fields (`conversationFieldDefinitions` + `customFieldDefinitions`)
- Status/priority enum options (values, labels, colors, order)
- Custom field definitions (Pain Points, Tech Stack, etc.) — labels, types, display order, `agentEditsForbidden`, per-field instructions
- Display config — which fields show on CRM card, overview tab layout
- Currently edited via `#crm-updater` write commands or the Conversation Fields tab
**Decision**: Should stage-specific required fields move to `[exit]` blocks in the playbook? Should field definitions have a `## Conversation fields` reserved section? Or stay in the AOP editor?
### CRM field mappings (`provider_configs[].defaultFieldMappings`)
- Maps Cedar internal fields to Salesforce/HubSpot field IDs
- Org-level config, currently in the Integrations tab
- Could move to an `@org/resources/crm-field-mappings.md` file
### Intelligence extraction fields
- Org-level metadata extraction definitions (moment fields, scorecard fields)
- Currently in the Intelligence tab, stored as Cedar Docs
- Likely stays as structured editor — not behavioral config
### Conversation scope config
- Multi-conversation mode, scope (user vs. org routing)
- Structural config, stays in AOP editor
### User settings
- Mail settings, notification settings, agent model/verbosity preferences
- Not AOP-specific, stays in Settings tab
---
## Willem migration (required before org rollout)
Convert Willem's existing legacy playbook from `organisation/playbooks/process/rep-{id}` to `user/playbooks/{aopId}/PLAYBOOK.md` format. The old format uses different trigger syntax and a flat document structure.
Reference: `tmp/willem-playbook-example.md` has the target format. Migration requires:
1. Reading the old document
2. Restructuring into `[on:trigger]...[/on]` blocks with proper stage sections
3. Migrating skill content (overall_goal, email_drafting, etc.) to resource files
4. Running `seedPlaybookFiles` + `migrateToPlaybook` for his AOP
---
## Tracking summary
| Phase | Description | Risk | Prerequisite |
|---|---|---|---|
| 1 | Remove hasPlaybook gates + legacy branches | Low | All AOPs have playbooks |
| 2 | Remove superseded tools (run-crm-updater, etc.) | Medium | Subagent files have full instructions |
| 3 | Drop aop_agents + aop_skills tables | High | Phase 1 + 2 complete; UI updated |
| 4 | Remove legacy context resolution | Medium | Phase 3 complete |
| 5 | AOP editor UI cleanup | Low | Phase 3 complete |