Orchestrata Ultimate › Plans › PROMPT-detailed-execution-plan
Prompt: Generate Detailed Iterative Execution Plan
Source: plans/PROMPT-detailed-execution-plan.md at 8a2cb42ad · last changed 2026-07-27 · first committed 2026-04-11 · 296 lines.
Prose pending.
Plan text
Prompt: Generate Detailed Iterative Execution Plan
Usage: Paste this entire prompt into a new Claude session with MAX THINKING enabled. The output will be a step-by-step plan executable by DeepSeek/Sonnet/Opus at medium effort.
Role
You are a Principal Python Engineer creating an extremely detailed, step-by-step execution plan for porting ~122K LOC from a monorepo (orchestrata, 26 packages) into a single-package project (orchestrata-ultimate). The plan must be detailed enough that a coding AI at medium effort (DeepSeek, Sonnet, or Opus) can follow each step without ambiguity — exact file paths, exact code patterns, exact verification commands, exact expected outputs.
Project Layout
Source (frozen, read-only):
/home/mohamed/workspace/orchestrata/packages/
orchestrata-core/src/orchestrata/core/
orchestrata-cxp/src/orchestrata/cxp/
orchestrata-agents/src/orchestrata/agents/
orchestrata-provider/src/orchestrata/provider/
orchestrata-llm/src/orchestrata/llm/
orchestrata-di/src/orchestrata/di/
orchestrata-drivers/src/orchestrata/drivers/
orchestrata-analyst/src/orchestrata/volks/analyst/
orchestrata-architect/src/orchestrata/volks/architect/
orchestrata-codedirector/src/orchestrata/volks/codedirector/
orchestrata-compliance/src/orchestrata/volks/compliance/
orchestrata-concierge/src/orchestrata/volks/concierge/
orchestrata-junior/src/orchestrata/volks/junior/
orchestrata-qa/src/orchestrata/volks/qa/
orchestrata-ux/src/orchestrata/volks/ux/
orchestrata-pm/src/orchestrata/volks/pm/
orchestrata-verification/src/orchestrata/verification/
orchestrata-governance/src/orchestrata/governance/
orchestrata-postman/src/orchestrata/postman/
orchestrata-kernel/src/orchestrata/kernel/
orchestrata-orchestrator/src/orchestrata/orchestrator/
orchestrata-knowledge/src/orchestrata/knowledge/
orchestrata-session/src/orchestrata/session/
orchestrata-memory/src/orchestrata/memory/
orchestrata-gateway/src/orchestrata/gateway/
orchestrata-plugin/src/orchestrata/plugin/
Target (work in progress):
/home/mohamed/workspace/orchestrata-ultimate/src/orchestrata_ultimate/
__init__.py
__main__.py
cli.py
agents/ (5 stub files: base_agent.py, architect.py, code_director.py, quality_assurance.py, user_experience.py)
core/ (REAL: logging/, metrics/, tracing/, patterns/, threading/, domain/, observability.py)
exceptions/ (REAL: exception hierarchy)
governance/ (STUB: pam.py)
integrations/ (STUBS: openrouter.py, todoist.py, vizint.py, cheetahclaws.py)
knowledge_graph/ (STUB: graph.py)
Reference Files
Before generating the plan, read these files from disk for full context:
-
plans/implementation-plan.md— The master plan (13 rounds of adversarial review, 800 lines). Contains module mapping, class mapping, import translation rules, phased implementation, bug lists, runtime concerns. THIS IS THE AUTHORITATIVE DOCUMENT. -
plans/ast-deep-comparison.json(336K) — Deep semantic comparison with:- 34 semantic class pairs with method-level signature diffs
- Per-package subsystem analysis with LOC/class counts
- Coverage gaps by tier
- 240 import translations
- Inheritance chains for all paired classes
- Unmapped classes grouped by package
-
plans/class-mapping.json— Semantic class/module/tier mapping configuration. -
plans/ast-ultimate.json(397K) — Full AST of orchestrata-ultimate: 37 modules, 57 classes, 147 methods, 6,231 LOC. -
plans/ast-orchestrata.json(8.0MB) — Full AST of orchestrata: 456 modules, 947 classes, 3,877 methods, 121,692 LOC.
Key Data Summary (embedded for quick reference)
Class Mapping (orchestrata -> ultimate)
BaseVolk -> BaseAgent (mostly_complete, 7->5 methods)
BaseEntity -> DomainEntity (mostly_complete, 6->7 methods)
CodeDirectorVolk -> CodeDirectorAgent (STUB, 16->4 methods, missing 15)
QaVolk -> QualityAssuranceAgent (STUB, 42->4 methods, missing 41)
AuditLogger -> AuditLogger (STUB, 27->3 methods, missing 26)
UXVolk -> UserExperienceAgent (partial, 6->4 methods)
OrchestrationKernel-> OrchestrataKernel (partial, 14->7 methods)
Orchestrator -> UltimateOrchestrator (partial, 11->5 methods)
PolicyEngine -> GovernanceEngine (partial, 11->6 methods)
Neo4jClient -> Neo4jGraph (partial, 14->8 methods)
CircuitBreaker -> CircuitBreaker (mostly_complete, 9->8 methods)
Node -> Node (mostly_complete, 2->4 methods)
WebSocketGateway -> VizIntWebUI (mostly_complete, 10->7 methods)
AnalystVolk -> AnalystAgent (NEEDS CREATION, 10 methods)
SeniorDevVolk -> SeniorDevAgent (NEEDS CREATION, 3 methods)
JuniorVolk -> JuniorAgent (NEEDS CREATION, 9 methods)
PMVolk -> ProjectManagerAgent (NEEDS CREATION, 7 methods)
ConciergeVolk -> ConciergeAgent (NEEDS CREATION, 5 methods)
ComplianceVolk -> ComplianceAgent (NEEDS CREATION, 9 methods)
VolkRuntime -> AgentRuntime (NEEDS CREATION, 24 methods)
VolkPool -> AgentPool (NEEDS CREATION, 8 methods)
VolkRegistry -> AgentRegistry (NEEDS CREATION, 33 methods)
VolkCoordinator -> AgentCoordinator (NEEDS CREATION, 12 methods)
ProviderManager -> ProviderManager (NEEDS CREATION, 16 methods)
SessionManager -> SessionManager (NEEDS CREATION, 13 methods)
MemoryEngine -> MemoryEngine (NEEDS CREATION, 14 methods)
EventBus -> EventBus (NEEDS CREATION, 14 methods)
Module Mapping (import translation)
from orchestrata.core.interfaces import X -> from orchestrata_ultimate.core.protocols import X
from orchestrata.core.traceability import X -> from orchestrata_ultimate.core.tracing import X
from orchestrata.core.infra_config import X -> from orchestrata_ultimate.core.config import X
from orchestrata.core.base import X -> from orchestrata_ultimate.core.domain import X
from orchestrata.<pkg>.* import X -> from orchestrata_ultimate.<pkg>.* import X
from orchestrata.volks.<role>.* import X -> from orchestrata_ultimate.agents.volks.<role>.* import X
Coverage by Tier
Tier 0 (core): orch=6,439 LOC -> ult=4,621 LOC = 71.8% covered
Tier 1 (agents/CXP): orch=28,226 LOC -> ult=0 LOC = 0.0% covered
Tier 1+2 (agents infra): orch=13,796 LOC -> ult=527 LOC = 3.8% covered
Tier 2 (coordination): orch=45,014 LOC -> ult=145 LOC = 0.3% covered
Tier 2+3 (knowledge): orch=8,449 LOC -> ult=110 LOC = 1.3% covered
Tier 3 (session/mem): orch=11,740 LOC -> ult=0 LOC = 0.0% covered
Tier 4 (gateway/plugin): orch=8,028 LOC -> ult=0 LOC = 0.0% covered
Subsystems (by size)
orchestrata-kernel tier=2 15,272 LOC 24 mods 118 cls
orchestrata-postman tier=2 12,674 LOC 31 mods 122 cls
orchestrata-orchestrator tier=2 11,332 LOC 35 mods 121 cls
orchestrata-session tier=3 10,595 LOC 37 mods 58 cls
orchestrata-cxp tier=1 9,525 LOC 34 mods 78 cls
orchestrata-knowledge tier=2+3 8,449 LOC 35 mods 79 cls
orchestrata-agents tier=1+2 7,338 LOC 31 mods 62 cls
orchestrata-verification tier=1+2 6,458 LOC 61 mods 53 cls
orchestrata-core tier=0 6,439 LOC 35 mods 74 cls
orchestrata-governance tier=2 5,736 LOC 19 mods 54 cls
orchestrata-gateway tier=4 4,429 LOC 25 mods 30 cls
orchestrata-codedirector tier=1 4,228 LOC 10 mods 6 cls
orchestrata-plugin tier=4 3,599 LOC 13 mods 32 cls
orchestrata-qa tier=1 3,039 LOC 2 mods 1 cls
orchestrata-drivers tier=1 1,961 LOC 10 mods 7 cls
orchestrata-provider tier=1 1,936 LOC 16 mods 18 cls
orchestrata-architect tier=1 1,708 LOC 8 mods 3 cls
orchestrata-pm tier=1 1,492 LOC 4 mods 11 cls
orchestrata-memory tier=3 1,145 LOC 7 mods 7 cls
orchestrata-di tier=1 856 LOC 2 mods 5 cls
orchestrata-compliance tier=1 766 LOC 3 mods 1 cls
orchestrata-analyst tier=1 729 LOC 4 mods 1 cls
orchestrata-llm tier=1 722 LOC 4 mods 3 cls
orchestrata-junior tier=1 623 LOC 2 mods 1 cls
orchestrata-concierge tier=1 381 LOC 2 mods 1 cls
orchestrata-ux tier=1 260 LOC 2 mods 1 cls
Known Bugs in Ultimate (fix in Phase 0)
1. Wrong import path logging_config.py:71 core.context -> core.logging.context
2. Deprecated API (6 locs) error_handling.py asyncio.iscoroutinefunction -> inspect.iscoroutinefunction
3. Race condition error_handling.py:307,348 Await circuit breaker state tasks
4. Race condition thread_pool.py:430,441 Protect _active_task_ids with lock
5. Memory leak thread_pool.py Cleanup completed tasks > 1000
6. Pydantic v1 node.py:40 Config -> model_config = ConfigDict(...)
7. Pydantic v1 domain_entity.py .dict() -> .model_dump()
8. Duration unrecorded decorators.py:144-149 Record duration in metric
9. No-op cleanup metrics_config.py:304-307 Implement stop function
10. Hardcoded state audit.py:376-379 Capture real after_state
New External Dependencies Needed
Real PyPI packages (not stdlib): click, fastapi, httpx, jinja2, jwt (pyjwt), msgpack,
neo4j, redis, watchfiles, websockets, yaml (pyyaml)
Conditional/optional: google-protobuf, grpcio (skip for now), pyswip
Architectural Decisions (non-negotiable)
1. BaseAgent uses Pydantic BaseModel + CXPMixin (not dataclass BaseEntity)
2. All other types (CXPPacket, Intent, Goal, etc.) stay as dataclasses
3. ABC interfaces become Protocol classes (PEP 544)
4. All external services use factory pattern with in-memory fallbacks
5. Volk -> Agent rename (class names, NOT module/file names during initial port)
6. 95 os.environ["X"] reads across orchestrata must become os.environ.get("X", default)
7. Python >=3.14 required
8. Zero mocking in tests
9. Three-pass import translation: bulk sed -> manual audit of 15 dynamic imports -> runtime fix
10. Stubs deleted only after 90%+ test pass rate
Task
Using MAX THINKING, generate a single comprehensive execution plan as one markdown document. This plan will be executed step-by-step by AI coding agents (DeepSeek, Sonnet, Opus) at medium effort — meaning each step must be unambiguous and self-contained.
Output Format
Structure the plan as follows:
# Execution Plan: Port Orchestrata -> Orchestrata-Ultimate
## How to Use This Plan
[Brief instructions for the executing agent: read one step, execute it, verify, move to next]
## Phase 0: Foundation (Steps 1-N)
### Step 1: [Short title]
**Goal:** [One sentence]
**Files to modify:**
- `src/orchestrata_ultimate/path/to/file.py` — [what changes]
**Actions:**
1. Open `src/orchestrata_ultimate/path/to/file.py`
2. On line N, change `old_code` to `new_code`
3. [exact code block if creating new code]
**Verification:**
```bash
command to run
Expected output: [exact text or pattern] If it fails: [what to check]
Step 2: ...
### Requirements for Each Step
1. **Exact paths** — never "the config file", always `src/orchestrata_ultimate/core/config/infra.py`
2. **Exact code** — never "update the import", always `change line 5 from 'from orchestrata.core.base import BaseEntity' to 'from orchestrata_ultimate.core.domain import DomainEntity'`
3. **Copy commands** — when porting a file, give the exact `cp` command from source to destination, then list every import line that needs changing in that file
4. **Verification after every step** — a command that proves the step worked. Usually `python -c "from orchestrata_ultimate.X import Y; print('OK')"` or `uv run pytest tests/specific_test.py -x`
5. **Small steps** — each step should take a medium-effort agent 1-3 minutes. If a step would take longer, split it.
6. **Dependencies explicit** — if step 15 depends on step 12, say so
7. **Gate checks** — after each sub-phase (0.1, 0.2, etc.), include a gate check that runs all tests and confirms pass count
8. **No ambiguity** — a developer who has never seen this codebase should be able to follow the plan
### What to Include for Each Porting Step
When the step is "port file X from orchestrata to ultimate":
1. The `cp` command (source -> destination, creating directories if needed)
2. Every `from orchestrata.` import in that file, with the exact replacement
3. Every `os.environ["X"]` in that file, with the exact `.get()` replacement and default value
4. Any class/function renames needed (Volk -> Agent, etc.)
5. Any base class changes (BaseEntity -> appropriate replacement)
6. Any type annotation updates
7. The verification command
### Scope
Generate the plan for ALL tiers (Phase 0 through Tier 4). It is fine if later tiers are slightly less granular than Phase 0 (because the executing agent will have learned the patterns by then), but every step must still have exact file paths and verification commands.
Estimated total steps:
- Phase 0: ~30-40 steps (bugs + core + test infra + pyproject)
- Tier 1: ~60-80 steps (CXP + providers + LLM + DI + drivers + verification subset + 11 volks)
- Tier 2: ~80-100 steps (knowledge subset + agent infra + governance + postman + kernel + orchestrator)
- Tier 3: ~30-40 steps (knowledge remainder + session + memory)
- Tier 4: ~20-30 steps (gateway + plugin + integrations)
Total: ~220-290 steps.
### Constraints
- Package manager: `uv` (never pip). Use `uv add <package>` for deps, `uv run pytest` for tests.
- Imports: absolute only (no relative imports)
- Testing: no mocking — real implementations only
- Git: commit after each sub-phase gate check (not after every step)
- Author: Mohamed (no AI attribution in commits)
- All new `__init__.py` files must have proper `__all__` exports
- Use `# type: ignore` sparingly and only when justified
- When a stub and real implementation coexist, the real one goes in the new location and the stub stays until tests pass
### Quality Criteria
The plan is good enough when:
1. A medium-effort AI agent can execute any step without asking clarifying questions
2. Every step has a verification command with expected output
3. File paths are never ambiguous
4. Import translations are exhaustive (not "update imports as needed")
5. The plan handles the 15 dynamic import locations explicitly
6. Gate checks verify cumulative test counts
7. The order respects all dependency chains (no circular references)
8. Each tier can be executed independently after its prerequisites pass
### Begin
Read the reference files, think deeply about the dependency chains and execution order, then generate the complete plan.
## Related
- [Plans](/projects/orchestrata-ultimate/plans/index)
- [Orchestrata Ultimate — project index](/projects/orchestrata-ultimate/index)
- [Workflow](/projects/orchestrata-ultimate/workflow)
- [Tasks](/projects/orchestrata-ultimate/tasks)