afv-library/skills/agentforce-bot-upgrade/references/planner-workflow-reference.md

Planner Workflow Reference

Use this reference during orchestrator Step 3 when processing multiple bots in a single invocation.

When To Apply

• Apply only when there are more than 1 ready-for-authoring Agent Specs.
• If there is 1 or fewer specs, skip planner workflow and keep specs unchanged.

Inputs

Required inputs to this workflow:

1. spec_paths: all ready-for-authoring Agent Spec paths
2. working_dir: orchestrator working directory where planner output must be written
3. associated artifacts for each spec when present:
   • handoff JSON
   • open questions

Required Workflow

1. Read all specs and associated artifacts.
2. Build a final candidate set of specs that will each map to one actual downstream agent.
3. Identify existing subagent grouping/context in each spec.
4. Attempt regrouping based on:
   • intent
   • underlying object/entity
   • broad category
5. Allowed structural operations across specs:
   • merge
   • split
   • move
   • delete
6. Apply operations only when they improve:
   • modularity
   • context-awareness
   • interactive user experience
7. Never perform changes for superficial consistency only.
8. Preserve full functional coverage:
   • no input functionality may be lost
   • if any functionality loss risk is detected, abandon changes and mark unchanged

Required Output File

Write:

• <working_dir>/bot-upgrade-planner-output.json

Schema:

{
  "specs_changed": true,
  "updated_specs": [
    {
      "original_spec_path": "/path/original/spec-a.md",
      "updated_spec_path": "/path/updated/spec-a.md",
      "run_project_dir": "/path/updated/run-project-dir",
      "handoff_json_path": "/path/updated/spec-a-einstein-bot-handoff.json",
      "open_questions_path": "/path/updated/spec-a-open-questions.md"
    }
  ]
}

Rules:

1. specs_changed is boolean.
2. If specs_changed=false, then updated_specs=[].
3. If specs_changed=true, updated_specs must include entries for all changed specs.
4. Every changed entry must include:
   • original_spec_path
   • updated_spec_path
   • run_project_dir
   • handoff_json_path
   • open_questions_path
5. If any functionality-loss risk exists, force:
   • specs_changed=false
   • updated_specs=[]